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The iRMX 86 and iRMX 88 I/O Systems are each implemented as a set of file 


drivers and a set of device drivers. File drivers provide the support 
for particular types of files (for example, the named file driver 
provides the support for named files). Device drivers provide the 
support for particular devices (for example, an iSBC 215 device driver 
provides the facilities that enable you to use an iSBC 215 Generic 
Winchester controller to control a Winchester-type drive with the I/0 
System). Each type of file has its own file driver, and each device has 
its own device driver. 


One of the reasons. that the I/O Systems are broken up in this manner is 
to provide device-independent I/O. Application tasks communicate with 
file drivers, not with device drivers. This allows tasks to manipulate 
all files in the same manner, regardless of the devices on which the 
files reside. File drivers, in turn, communicate with device drivers, 
which provide the instructions necessary to manipulate physical devices. 
Figure 1-1 shows these levels of communication. 
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Figure 1-1. Communication Levels 
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INTRODUCTION 


The I/O System provides a standard interface between file drivers and 
device drivers. To a file driver, a device is merely a standard block of 
data in a table. To manipulate a device, the file driver calls the 
device driver procedures listed in the table. To a device driver, all 
file drivers seem the same. Every file driver calls device drivers in 
the same manner. This means that the device driver does not need to 
concern itself with the concept of a file driver. It sees itself as 
being called by the I/O System, and it returns information to the 1/0 
System. This standard interface has the following advantages: 


e The hardware configuration can change without extensive 
modifications to the software. Instead of modifying entire file 
drivers when you want to change devices, you need only substitute 
a different device driver and modify the table. 


e The I/O System can support a greater range of devices. It can 
support any device, as long as you supply a device driver that 
interfaces to the file drivers in the standard manner. 


I/O DEVICES AND DEVICE DRIVERS 


Each I/O device consists of a controller and one or more units. A device 
as a whole is identified by a unique device number. Units are identified 
by unit number and by device-unit number. The device number identifies 
the controller among all the controllers in the system, the unit number 
identifies the unit within the device, and the unique device-unit number 
identifies the unit among all the units of all of the devices. Figure 
1-2 contains a simplified drawing of three I/O devices and their device, 
unit, and device-unit numbers. 
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Figure 1-2. Device Numbering 
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INTRODUCTION 


You must provide a device driver for every device in your hardware 
configuration. That device driver must handle the I/O requests for all 
of the units the device supports. Different devices can use different 
device drivers; or if they are the same kind of device, they can share 
the same device driver code. (For example, two iSBC 215 controllers are 
two separate devices and each has its own device driver. However, these 
device drivers can share common code.) 


I/O REQUESTS 


To the device driver, an I/U request is a request by the I/O System for 
the device to perform a certain operation. Operations supported by the 
I/O System are: 


Read 

Write 

Seek 

Special 
Attach device 
Detach device 
Open 

Close 


The I/O System makes an I/O request by sending to the device driver an 
I/O request/result segment (IORS) containing the necessary information. 
(The IORS is described in Chapter 2.) The device driver must translate 
this request into specific device commands to cause the device to perform 
the requested operation. 


TYPES OF DEVICE DRIVERS 


The I/O System supports four types of device drivers: custom, common, 
random access, and terminal. A custom device driver is one that the user 
creates in its entirety. This type of device driver can assume any form 
and can provide any functions that the user wishes, as long as the I/0 
System can access it by calling four procedures, designated as Initialize 
I/O, Finish I/0, Queue I/0, and Cancel I/O. 


The 1/0 System provides the basic support routines for the common, random 
access, and terminal device driver types. These support routines provide 
a queueing mechanism, an interrupt handler, and other features needed by 
common, random access, and terminal devices. If your device fits into 
the common, random access, or terminal device classification, you need to 
write only the specialized, device-dependent procedures and interface 
them to the ones provided by the I/O System to create a complete device 
driver. 
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INTRODUCTION 


HOW TO READ THIS MANUAL 


This manual is for people who plan to write device drivers for use with 
iRMX 86- and/or iRMX 88-based systems. Because there are numerous 
terminology differences between the two iRMX systems, the tone of this 
manual is general, unlike that of other manuals for either system. For 
iRMX 88 users, this should not be a problem. But iRMX 86 users should 
take note of the following: 


e In a number of places the phrase "the location of" is substituted 
for "a token for". 


e The "device data storage area” that is alluded to in many places 
is actually an iRMX 86 segment. 


e The term “resources” usually means "objects." The intended 
meaning of “resources” is clear from its context. 


week 
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DEVICE DRIVER INTERFACES 


Because a device driver is a collection of software routines that manages 
a device at a basic level, it must transform general instructions from 
the I/O System into device-specific instructions which it then sends to 
the device itself. Thus, a device driver has two types of interfaces: 


e An interface to the I/O System, which is the same for all device 
drivers. 


e An interface to the device itself, which varies according to 
device. 


This chapter discusses these interfacese 


T/O SYSTEM INTERFACES 


The interface between the device driver and the I/O System consists of 
two data structures: the device-unit information block (DUIB) and the I/O 
request/result segment (IORS). 


DEVICE-UNIT INFORMATION BLOCK (DUIB) 


The DUIB is an interface between a device driver and the I/O System, in 
the sense that the DUIB contains the addresses of one of the following 
routines: 


e The device driver routines (in the case of custom device drivers). 


e The device driver support routines (in the case of terminal 
drivers, common drivers, and random access drivers). 


By accessing the DUIB for a unit, the I/O System can call the appropriate 
device driver/device driver support routine. All devices, no matter how 
diverse, use this standard interface to the I/O Systeme You must provide 
a DUIB for each device-unit in your hardware systeme You supply the 
information for your DUIBs as part of the configuration process. 
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CHAPTER 2 


DEVICE DRIVER INTERFACES 


DUIB Structure 


This section lists the elements that make up a DUIB.e When creating DUIBs 
for iRMX 86 applications, code them in the format shown here (as 
assembly-language structures). The iRMX 86 Interactive Configuration 
Utility (ICU) includes your DUIB file in the assembly of IDEVCF.A86 (a 
Basic I/O System configuration file). IDEVCF.A86 contains the definition 
of the structure. 


Unlike the iRMX 86 ICU, the iRMX 88 ICU prompts you for some fields in 
the DUIB structuree The ICU automatically fills in the other fields, 
depending upon factors such as the type of device you are configuring. 
The iRMX 88 ICU generates the DUIBs and places them in the device 
configuration source file. 


DEFINE DUIB < 


& NAME (14), 3; byte (14) 

& FILESDRIVERS , 3; word 

& FUNCTS , 3; byte 

& FLAGS, 3; byte 

& DEVSGRAN, 3; word 

& DEVSSIZE, ; dword 

& DEVICE, 3; byte 

& UNIT, 3; byte 

& DEVSUNIT, 3 word 

&  INITSIO, 3; word 

& FINISHSIO, ; word 

& QUEUESIO, 3 word 

& CANCELSIO, 3; word 

&  DEVICESINFOSP, 3; pointer 

& UNITSINFOSP, ; pointer 

& UPDATESTIMEOUT , 3; word 

& NUMSBUFFERS, 3 word 

& PRIORITY, 3; byte 

& | FIXEDSUPDATE, ; byte (iRMX 86 DUIB only) 
& | MAXSBUFFERS, 3 byte (iRMX 86 DUIB only) 
& RESERVED, ; byte (iRMX 86 DUIB only) 
& > 
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where: 


NAME 


FILE$DRIVERS 


FUNCTS 


DEVICE DRIVER INTERFACES 


A 14-BYTE array specifying the name of the DUIB. 


This name uniquely identifies the device-unit to 
the I/O System. Use only the first 13 bytes. The 
fourteenth is used by the I/O System. 


You supply the name when configuring your 
application system. If you are an iRMX 86 user, 
you specify the DUIB name when attaching a unit via 
the RQ$A$PHYSICAL$ATTACH$DEVICE system call. 

Device drivers can ignore this field. 


For the iRMX 88 Executive, the DUIB name is the 
device name portion of the name$p parameter for the 
DQ$ATTACH or the DQ$CREATE system calls. 


WORD specifying file driver validity. Setting bit 
number "i" of this word implies that the 


corresponding file driver can attach this 
device-unit. Clearing bit number "i" implies that 


the file driver cannot attach this device-unit. 


The low-order bit is bit 0. The bits are 
associated with the file drivers as follows: 


Bit "i" File Driver 
0 physical 
1 stream (iRMX 86 only) 
3 named 


The remaining bits of the word must be set to 
zero. Device drivers can ignore tnis field. 


BYTE specifying the I/O function validity for this 
device-unit. Setting bit number "i" implies that 
the device-unit supports the corresponding 
function. Clearing bit number "i" implies that the 
device-unit does not support the function. The 
low-order bit is bit 0. The bits are associated 
with the functions as follows: 


Bit “i" Function 


read 


write 
seek 


special 
attach device 
detach device 
open 

close 


NO UDP WHE © 


Bits 4 and 5 should always be set. Every device 
driver requires these functions. 
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FLAGS 


DEV$GRAN 


DEV$SIZi 


DEVICE 


DEVICE DRIVER INTERFACES 


This field is used for informational purposes 

only. Setting or clearing bits in this field does 
not limit the device driver from performing any I/0 
function. In fact, each device driver must be able 
to support any I/O function, either by performing 
the function or by returning a condition code 
indicating the inability of the device to perform 
that function. However, to provide accurate status 
information, this field should indicate the 
device's ability to perform the I/O functions. 
Device drivers can ignore this field. 


BYTE specifying characteristics of diskette 
devices. The significance of the bits is as 
follows, with bit 0 being the low-order bit: 


Bit Meaning 
0 0 = bits 1-7 not significant 
1 = bits 1-7 significant 
1 0 = single density; 1 = double 
density 
2 0 = single sided; 1 = double 
sided 
3 O = 8-inch diskettes 
1 = 5 1/4-inch diskettes 


> 
oO 
HT] 


standard diskette, meaning 
that track O is 
single-density with 
128-byte sectors 


1 = not a standard diskette or 
not a diskette 


5-7 reserved 


If bit 0 is set to 1, then a driver for the device 


can read track 0 when asked to do so by the I/0 
System. 


WORD specifying the device granularity, in bytes. 
This parameter applies to random access devices. 
It specifies the minimum number of bytes of 
information that the device reads or writes in one 
operation.If the device is a disk or magnetic 
bubble device, you should set this field equal to 
the sector size for the device. Otherwise, set 
this field equal to zero. 


DWORD specifying the number of bytes of information 
that the device-uni.t can store. 


BYTE specifying the device number of the device 


with which this device-unit is associated. Device 
drivers can ignore this field. 
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UNIT 


DEV$UNIT 


INIT$IO 


FINISH$IO 


QUEUE$ IO 


CANCEL$ IO 


DEVICE$ INFO$P 


UNIT$INFO$P 


DEVICE DRIVER INTERFACES 


BYTE specifying the unit number of this 


device-unit. This distinguishes the unit from the 
other units of the device. 


WORD specifying the device-unit number. This 
number distinguishes the device-unit from the other 
units in the entire hardware system. Device 
drivers can ignore this field. 


WORD specifying the address of the Initialize 1/0 
procedure associated with this unit. When creating 
the DUIB, use the procedure name as a variable to 
supply this information. Device drivers can ignore 
this field. 


WORD specifying the address of the Finish 1/0 
procedure associated with this unit. When creating 
the DUIB, use the procedure name as a variable to 
supply this information. Device drivers can ignore 
this field. 


WORD specifying the address of the Queue I/0 
procedure associated with this unit. When creating 
the DUIB, use the procedure name as a variable to 


supply this information. Device drivers can ignore 
this field. 


WORD specifying the address of the Cancel I/0 
procedure associated with this unit. When creating 
the DUIB, use the procedure name as a variable to 
supply this information. Device drivers can ignore 
this field. 


POINTER to a structure which contains additional 
information about the device. The common, random 
access, and terminal device drivers require, for 
each device, a Device Information Table, in a 
particular format. 


This structure is described in Chapter 3. If you 
are writing a custom driver, you can place 
information in this structure depending on the 
needs of your driver. Specify a zero for this 
parameter if the associated device driver does not 
use this field. 


POINTER to a structure that contains additional 
information about the unit. Random access and 
terminal device drivers require this Unit 
Information Table in a particular format. Refer to 
Chapter 3 for further information. If you are 
writing a custom device driver, place information 
in this structure, depending on the needs of your 
driver. Specify a zero for this parameter if the 
associated device driver does not use this field. 
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UPDATE$ TIMEOUT 


NUM$BUFFERS 


PRIORITY 


FIXED$UPDATE 


DEVICE DRIVER INTERFACES 


WORD specifying the number of system time units 
that the I/O System must wait before writing a 
partial sector after processing a write request for 
a disk device. In the case of drivers for devices 
that are neither disk nor magnetic bubble devices, 
set this field to UFFFFH during configuration. 

This field applies only to the device for which 
this is a DUIB, and is independent of updating that 
is done either because of the value in the 
FIXED$UPDATE field of the DUIB or by means of the 
A$UPDATE system call of the I/O System. Device 
drivers can ignore this field. 


WORD which, if not zero, both specifies that the 
device is a random access device and indicates the 
number of buffers the I/O System allocates. ‘The 
I/O System uses these buffers to perform data 
blocking and deblocking operations. That is, it 
guarantees that data is read or written beginning 
on sector boundaries. If you desire, the random 
access support routines can also guarantee that no 
data is written or read across track boundaries in 
a single request (see the section on the Unit 
Information Table in Chapter 3). A value of zero 
indicates that the device is not a random access 
device. Device drivers can ignore this field. 


BYTE specifying the priority of the I/0 System 
service task for the device. Device drivers can 
ignore this field. 


BYTE indicating whether the fixed update option was 
selected for the device when the application system 
was configured. This option, when selected, causes 
the I/O System to finish any write requests that 
had not been finished earlier because less than a 
full sector remained to be written. Fixed updates 
are performed throughout the entire system whenever 
a time interval (specified during configuration) 
elapses. This is independent of the updating that 
is indicated for a particular device (by the 
UPDATE$TIMEOUT field of the DUIB) or the updating 
of a particular device that is indicated by the 
A$UPDATE system call of the I/0 System. 


A value of OFFH indicates that fixed updating has 


been selected for this device, and a value of zero 
indicates that it has not been selected. Device 
drivers can ignore this field. 


The FIXED$UPDATE field is not present in the 
iRMX 88 DUIB. 
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MAX$BUFFERS BYTE specifying the maximum number of buffers that 
the Extended I/0 System (of the iRMX 86 Operating 
System) can allocate for a connection to this 
device when the connection is opened by a call to 
S$OPEN. The value in this field is specified 
during configuration. Device drivers can ignore 
this field. 


The MAX$BUFFERS field is not present in the iRMX 88 
DUIB. 


RESERVED BYTE reserved for future use. 


The RESERVED field is not present in the iRMX 88 
DUIB. 


Using the DUIBs 


To use the I/O System to communicate with files on a device-unit, you 
must first attach the unit. If you are an iRMX 88 user, attaching the 
unit occurs automatically when you first attach or create a file on the 
unit. If you are an iRMX 86 user, you attach the unit by invoking the 
RQ$A$PHYSICAL$ATTACH$DEVICE system call (refer to the iRMX 86 BASIC I/O 
SYSTEM REFERENCE MANUAL for a description of this system call). 


When you attach a unit, the I/O System assumes that the device-unit 
identified by the device name field of the DUIB has the characteristics 
identified in the remainder of the DUIB. Thus, whenever the application 
software makes an I/O request via the comnection to the attached 
device-unit, the I/O System ascertains the characteristics of that unit 
by examining the associated DUIB. The I/O System looks at the DUIB and 


calls the appropriate device driver/device driver support routines listed 
there to process the I/O request. 


If you want the I/O System to assume different characteristics at 
different times for a particular device-unit, you can supply multiple 
DUIBs, each containing identical device number, unit number, and 
device-unit number parameters, but different DUIB name parameters. Then 
you can select one of these DUIBs by specifying the appropriate dev$name 
parameter in the RQ$A$PHYSICAL$ATTACH$DEVICE system call (for iRMX 36 
users) or the appropriate device name when calling DQ$ATTACH or DQ$CREATE 
(for iRMX 88 users.) However, before you can switch the DUIBs for a 
unit, you must detach the unit. 


Figure 2-1 tllustrates this concept. It shows six DUIBs, two for each of 
three units of one device. The main difference within each pair of DUIBs 
in this figure is the device granularity parameter, which is either 123 
or 512. With this setup, a user can attach any unit of this device with 
one of two device granularities. In Figure 2-l, units 0 and 1 are 


attached with a granularity of 128 and unit 2 with a granularity of 512. 
To change this, the user can detach the device and attach it again using 
the other DUIB name. 
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NOTE 


For iRMX 86 systems only, when the 

I/O System accesses a device containing 
named files, it obtains information 
such as granularity, density, size 
(5-1/4" or 8" for diskettes), or the 
number of sides (single or double) from 
the volume label. Therefore it is not 
necessary to supply a different DUIB 
for every kind of volume you intend to 
use. However, for iRMX 86 
applications, you must supply a 
separate DUIB for every kind of volume 
you intend to format via the FORMAT 
Human Interface command. 












NAME = UNITA NAME = UNITA1 
DEVSGRAN = 128 DEVSGRAN = 512 


DUIBS FOR 
DEVICE-UNIT 6 


DEVICE =1 DEVICE = 1 
UNIT=0 UNIT =0 
DEVSUNIT =6 DEVSUNIT = 6 





CALL RQ$ASPHYSICALSATTACHSDEVICE (UNITA....) 






NAME = UNITB NAME = UNITB1 
DEVSGRAN = 128 DEVSGRAN = 512 

, DUIBS FOR 
DEVICE =1 DEVICE =1 pEvICe VEN? 
UNIT =1 UNIT = 1 
DEVSUNIT = 7 DEVSUNIT = 7 








CALL RQSAS$PHYSICALSATTACHSDEVICE (UNITB....) 


NAME = UNITC NAME = UNITC1 
DEVSGRAN = 128 DEVSGRAN = 512 

DUIBS FOR 
DEVICE = 1 DEVICE = 1 DEVICE-UNIT & 


UNIT = 2 


UNIT = 2 
DEVSUNIT = B 


DEVSUNIT = 8 





x-292 
CALL RQSASPHYSICALSATTACHSDEVICE (UNITC1,...) 


Figure 2-1. Attaching Devices 





Creating DUIBs 


During interactive configuration, you must provide the information for 
all of the DUIBs. The configuration ftle, which the ICU produces, sets 
up the DUIBs when it executes. Observe the following guidelines when 
supplying DUIB information: 
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e Specify a unique name for every DUIB, even those that describe 
the same device-unit. 


e For every device-unit in the hardware configuration, provide 
information for at least one DUIB. Because the DUIB contains the 
addresses of the device driver/device driver support routines, 
this guarantees that no device-unit is left without a device 
driver to handle its I/O. 


® Make sure to specify the same device driver/device driver support 
procedures in all of the DUIBs associated with a particular 
device. There is only one set of device driver/device driver 
support routines for a given device, and each DUIB for that 
device must specify this unique set of routines. 


® If you write a common or random access device driver, you must 


supply a Device Information Table for each device. If you write 
a random access device driver, you must also supply a Unit 


Information Table for each unit. See Chapter 4 for 
specifications of these tables. If you are using custom device 
drivers and they require these or similar tables, you must supply 
them, as well. 


e For iRMX 86 systems only, if you write a terminal driver, you 


must supply terminal device information table for each terminal 
device driver, as well as a unit information table for each 
terminal. See Chapter 7 for specifications of these tables. 


I/O REQUEST/RESULT SEGMENT (IORS) 


An I/O request/result segment (IORS) is the second structure that forms 
an interface between a device driver and the I/O System. The I/0 System 
creates an IORS when a user requests an I/O operation. The IORS contains 
information about the request and about the unit on which the operation 
is to be performed. The I/O System passes the IORS to the appropriate 
device driver, which then processes the request. When the device driver 
performs the operation indicated in the IORS, it must modify the IORS to 
indicate what it hds done and send the IORS back to the response mailbox 
(exchange) indicated in the IORS. 


The IORS is the only mechanism that the I/O System uses to transmit 


requests to device drivers. The IORS structure is always the same. 
Every device driver must be aware of this structure and must update the 


information in the IORS after performing the requested function. The 
IORS is structured as follows: 
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DECLARE 
IORS STRUCTURE( 
STATUS WORD, 
UNIT$STATUS WORD, 
ACTUAL WORD, 
ACTUAL$F ILL WORD, 
DEVICE WORD, 
UNIT BYTE, 
FUNCT BYTE, 
SUBFUNCT WORD, 
DEV$LOC DWORD, 
BUFF$P POINTER, 
COUNT WORD, 
COUNT$FILL WORD, 
AUX$P POINTER, 
LINK$FOR POINTER, 
LINK$BACK POINTER, 
RES P$MBOX SELECTOR, 
DONE BYTE, 
FILL BYTE, 
CANCEL$ID SELECTOR, 
CONN$T SELECTOR); (iRMX 86 IORS only) 
where: 

STATUS WORD in which the device driver must place the 
condition code for the I/O operation. The E$OK 
condition code indicates successful completion of the 
operation. For a complete list of possible condition 
codes, see either the iRMX 86 NUCLEUS REFERENCE 
MANUAL, the iRMX 86 BASIC I/O SYSTEM REFERENCE 
MANUAL, and the iRMX 36 EXTENDED I/O SYSTEM REFERENCE 
MANUAL, or the iRMX 88 REFERENCE MANUAL. 

UNIT$STATUS WORD in which the device driver must place additional 


status information if the status parameter was set to 
indicate the E$IO condition. The unit status codes 
and their descriptions are as follows: 


Code Mnemonic Description 

0 LO$UNCLASS Unclassified error 

1 IO$SOFT Soft error; a retry is possible 

2 IO$HARD Hard error; a retry is 
impossible 

3 LO$OPRINT Operator intervention is 
required 

4 LO$WRPROT Write-protected volume 

5% IO$NO$DATA No data on the next tape record 

6* LO$MODE A read (or write) was attempted 


before the previous write (or 
read) completed 


*For iRMX 86 systems only. 
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ACTUAL$FILL 


DEVICE 


UNIT 


FUNCT 


SUBFUNCT 
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The I/O System reserves values 0 through 3 (the least 
Significant four bits) of this field for unit status 
codes. The high 12 bits of this field can be used 
for any other purpose that you wish. For example, 
the iSBC 204 driver places the controller's result 
byte in the high eight bits of this field. For more 
information about the data returned by your device 


controller, refer to the hardware reference manual 
for your controller. 


WORD which the device driver must update upon 
completion of an I/O operation to indicate the number 
of bytes of data actually transferred. 


Reserved WORD. 


WORD into which the I/O System places the number of 
the device for which this request is intended. 


BYTE into which the L/O System places the number of 
the unit for which this request is intended. 


BYTE into which the I/O System places the function 
code for the operation to be performed. Possible 
function codes are: 


Code Function 
F$READ 
FSWRITE 
F$SEEK 
F$SPECIAL 
FSATTACH$DEV 
FSDETACH$DEV 
FSOPEN 
F$CLOSE 


NOU PWN RO 


WORD into which the I/O System places the actual 
function code of the operation, when the F$SPECIAL 
function code was placed into the FUNCT field. The 


value in this field depends upon the file driver to 
be used with this device. The possible subfunctions 


and the driver types to which they apply are as 
follows: 


File Driver Subfunct 

For Connection Value Function 

Physical* 0 Format track 

Stream 0 Query 

Stream 1 Satisfy 

Physical or Named Z Notify 

Physical 3 Get disk/tape 
data 
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File Driver Subfunct 

For Connection Value Function 

Physical 4 Get terminal data 

Physical 5 Set terminal data 

Physical 6 Set signal 

Physical 7 Rewind tape 

Physical 8 Read tape file 
mark 

Physical 9 Write tape file 
mark 

Physical 10 Retension tape 

11-32767 Reserved for 

other Intel 
products 


*These functions apply both to iRMX 86 and 
iRMX 88 systems. The other functions are 
LRMX 86-specific. 


The values from 32768 to 65535 are available for 
user-written/custom device drivers. 


DWORD into which the I/O System initially places the 
absolute byte location on the 1/0 device where the 
operation is to be performed. For example, for a 
write operation, this is the address on the device 
where writing begins. The I/O System fills out this 
information when it passes the IORS to the driver 
support routines. 


If the device driver is a random access driver, the 
random access support routines modify the information 
in the DEV$LOC field before passing the IORS on to 
user-written driver procedures listed in Chapter 5. 
The value that the random access support routines 
fill out depends upon the TRACK$SIZE field in the 
unit's Unit Information Table (see Chapter 3). 


e If the TRACK$SIZE field is zero, the random 
access support routines divide the value in 
DEV$LOC by the device granularity and place that 


ee (the absolute sector number) in the DEV$LOC 
field. 


e If the TRACK$SIZE field is nonzero, the random 
access support routines use the absolute byte 
number in DEV$LOC to calculate the track and 
sector numbers. The routines then place the 
track number in the high-order WORD (of DEV$LOC) 


and the sector number in the low-order WORD (of 
DEV$LOC). 


POINTER which the I/0 System sets to indicate the 
internal buffer where data is read from or written to. 
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WORD which the I/O System sets to indicate the number 
of bytes to transfer. 


Reserved WORD. 


POINTER which the I/0 System can set to indicate the 
location of auxiliary data. Normally, the I/O System 


uses AUX$P to pass or receive the additional data 
that the various subfunctions of the SPECIAL call 
require. 


The following paragraphs define the particular data 


structures pointed to by AUX$P. The data structure 
actually pointed to depends upon the SUBFUNCT field 
of the IORS. 


In a request to format a track on a disk or diskette, 
FUNCT equals special, SUBFUNCT equals format track, 
and AUX$P points to a structure of the form: 


DECLARE FORMAT$TRACK STRUCTURE( 
TRACK$NUMBER WORD, 


INTERLEAVE WORD, 
TRACK$OFFSET WORD, 
FILL$CHAR BYTE) ; 


These fields are defined as follows: 


track$number The number of the track to be 
formatted. Acceptable values are 0 to 
(number of tracks on the volume — 1). 


interleave The interleaving factor for the track. 
(That is, the number of physical 
sectors to advance when locating the 
next logical sector.) The supplied 
value, before being used, is evaluated 
MOD the number of sectors per track. 


track$offset The number of physical sectors to 
advance when locating the first logical 


sector on the next track. 

fill$char The byte value with which each sector 
is to be filled. 
NOTE 


The rest of the information about the 
AUX$P field is iRMX 86-specific. 
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In a request to set up an iRMX 86 mailbox, where the 
iRMX 86 I/O System is to send an object whenever a 
door to a flexible disk drive is opened or the STOP 
button on a hard disk drive is pressed, FUNCT equals 
special, SUBFUNCT equals notify, and AUX$P points to 
a structure of the form: 


DECLARE SETUP$NOTIFY STRUCTURE( 
MAILBOX SELECTOR, 
OBJECT SELECTOR) ; 


where the fields are defined in the iRMX 86 BASIC I/O 
SYSTEM REFERENCE MANUAL. Random access drivers do 


not have to process such requests because they are 
handled by the I/O System. 


In a request to obtain information about iSBC 215 or 


iSBC 220 (supported) disk devices, FUNCT equals 
special, SUBFUNCT equals get device characteristics, 
and AUX$P points to a structure of the form: 


DECLARE DISK$DRIVE$DATA STRUCTURE( 


CYLINDERS WORD, 
FIXED BYTE, 
REMOVABLE BYTE, 
SECTORS BYTE, 
SECTOR$SIZE WORD, 
ALTERNATES BYTE); 


where the fields are defined in the iRMX 86 BASIC I/O 
SYSTEM REFERENCE MANUAL. 


In a request to obtain information about iSBX 217 
tape drives (associated with an iSBC 215G board), 
FUNCT equals special, SUBFUNCT equals get device 
characteristics, and AUX$P points to a structure of 
the form: 


DECLARE TAPESDRIVE$DATA STRUC'TURE( 
TAPE WORD, 
RESERVED(7) BYTE); 


where the fields are defined in the iRMX 86 BASIC I/O 
SYSTEM REFERENCE MANUAL. 


In a request to read or write terminal mode 
information for a terminal being driven by a terminal 
driver, FUNCT equals special, SUBFUNCT equals get 
terminal attributes (for reading) or set terminal 


attributes (for writing), and AUX$P points to a 
structure of the form: 
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DECLARE TERMINAL$ATIRIBUTES STRUCTURE( 


NUM$WORDS 
NUM$USED 
CONNECTION$FLAGS 
TERMINAL$FLAGS 
IN$BAUD$RATE 
OUT$BAUD$RATE 
SCROLL$LINES 
X$Y$SIZE 
X$Y$OFFSET 
FLOW$CONTROL 
HIGH$WATER$MARK 
LOWSWATER$MARK 
FCSON$CHAR 
FCS$OFF$CHAR 


WORD, 
WORD, 
WORD, 
WORD, 
WORD, 
WORD, 
WORD, 
WORD, 
WORD, 
WORD, 
WORD, 
WORD, 
WORD, 
WORD); 


where the fields are defined in the iRMX 86 BASIC I/0 


SYSTEM REFERENCE MANUAL. 


If you are using the 


Terminal Support Code, this special subfunction is 
invisible to the terminal device driver. 


In a request to set up special character recognition 
in the input stream of a terminal driver for 
signalling purposes, FUNCT equals special, SUBFUNCT 
equals signal, and AUX$P points to a structure of the 


form: 


DECLARE SIGNAL$CHARACTER STRUCTURE( 


SEMAPHORE 
CHARACTER 


SELECTOR 
BYTE); 


where the fields are defined in the iRMX 86 BASIC I/O 


SYSTEM REFERENCE MANUAL. 


In a request to read a tape 


file mark, FUNCT equals special, SUBFUNCT equals read 
tape file mark, and AUX$P points to a structure of 


the form: 


DECLARE READ$FILE$MARK STRUCTURE( 


SEARCH 


BYTE); 


where the field is defined in the iRMX 86 BASIC I/O 


SYSTEM REFERENCE MANUAL. 


POINTER that the device driver/device driver support 
routines can use to implement a request queue. This 
field points to the location of the next IORS in the 


queue. 


POINTER that the device driver/device driver support 


routines can use to implement a request queue. This 
field points to the Location of the previous IORS in 


the queue. 


Device Drivers 2-15 


DEVICE DRIVER INTERFACES 


RES P$MBOX SELECTOR that the I/0 System fills with either an 
iRMX 86 token for the response mailbox or the address 
of an iRMX 88 exchange. Upon completion of the I/0 
request, the device driver/device driver support 
routines must send the IORS to this response mailbox 
or exchange. 


DONE BYTE that the device driver can set to TRUE (OFFH) or 
FALSE (00H) to indicate whether the entire request 
has been completed. 


FILL Reserved BYTE. 


CANCEL$ID SELECTOR used to identify queued I/O requests that 
CANCEL$IO can remove from the queue. 


CONN$T SELECTOR used in requests to the iRMX 86 I/O System. 
This field contains the token of the iRMX 86 file 
connection through which the request was issued. 


DEVICE INTERFACES 


To carry out I/O requests, one or more of the routines in every device 
driver must actually send commands to the device itself. The steps that 
a procedure of this sort must go through vary considerably, depending on 
the type of I/0 device. Procedures supplied with the I/O System to 
manipulate devices such as the iSBC 204 and iSBC 206 devices use the 
PL/M-86 builtins INPUT and OUTPUT to transmit to and receive from 1/0 
ports. Other devices may require different methods. The I/O System 


places no restrictions on the method of communicating with devices. Use 
the method that the device requires. 


KKK 
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CHAPTER 3 
CATEGORIES AND PROPERTIES 
OF DEVICES AND DRIVERS 





There are four types of device drivers in the iRMX 86 environment: 
common, random access, custom, and terminal. There are three types of 
device drivers in the iRMX 88 environment: common, random access, and 
custom. This chapter defines the distinctions between the types of 


drivers and discusses the characteristics and data structures pertaining 
to common and random access device drivers. Chapters 5, 6, and 7 are 
devoted to explaining how to write the various types of device drivers. 


CATEGORIES OF DEVICES 


Because the I/O System provides procedures that constitute the bulk of 


any common or random access device driver, you should consider the 
possibility that your device is a common or random access device. If 
your device falls in either of these categories, you can avoid most of 
the work of writing a device driver by using the supplied procedures. 
The following sections define the four types of devices. 


COMMON DEVICES 


Common devices are relatively simple devices other than terminals, such 


as line printers. This category includes devices that conform to the 
following conditions: 


e A first-in/first-out mechanism for queuing requests is sufficient 
for accessing these devices. 


e Only one interrupt level is needed to service a device. 


e Data either read or written by these devices does not need to be 
broken up into blocks. 


If you have a device that fits into this category, you can save the 
effort of creating an entire device driver by using the common driver 
routines supplied by the I/O System. Chapter 5 of this manual describes 
the procedures that you must write to complete the balance of a common 
device driver. 


RANDOM ACCESS DEVICES 


A random access device is a device, such as a disk drive, in which data 


can be read from or written to any address of the device. The support 
routines provided by the I/O System for random access assume the 
following conditions: 
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e A first-in/first-out mechanism for queuing requests is sufficient 
for accessing these devices. 


e Only one interrupt level is needed to service the device. 
e I/O requests must be broken up into blocks of a specific length. 
e The device supports random access seek operations. 


If you have devices that fit into the random access category, you can 
take advantage of the random access support routines provided by the I/0 
System. Chapter 5 of this manual describes the procedures that you must 
write to complete the balance of a random access device driver. 


TERMINAL DEVICES 


A terminal device is characterized by the fact that it reads and writes 


single characters, with an interrupt for each character. Because such 
devices are entirely different than common, random access, and even 


custom devices, terminal drivers and their required data structures are 
described in Chapter 7. The remainder of this chapter applies only to 
common, random access, and custom device drivers. 


CUSTOM DEVICES 


If your device fits neither the common ner the random access category, 
and is not a terminal or terminal-like device, you must write the entire 
driver for the device. ‘The requirements of a custom device driver are 
defined in Chapter 6. 


I/O SYSTEM-SUPPLIED ROUTINES FOR COMMON AND RANDOM ACCESS DEVICE DRIVERS 


The I/O System supplies the common and random access routines that it 
calls when processing I/O requests. Flow charts for these procedures 
appear in Appendix A. The names and funetions of these procedures are as 
follows: (The “RAD$" prefix applies to iRMX 88 routine names.) 


Routine Function 
(RAD$) INIT$IO Creates the resources needed by the remainder of 


the driver routines, creates an interrupt task, 
and calls a user-supplied routine that 
initializes the device itself. 


(RAD$) FINISH$ 10 Deletes the resources used by the other driver 
routines, deletes the interrupt task, and calls a 
user-supplied procedure that performs final 
processing on the device itself. 
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Routine Function 

(RAD$ ) QUEUE$LO Places I/O requests (IORSs) on the queue of 
requests. 

(RAD$ ) CANCEL$ IO Removes one or more requests from the request 


queue, possibly stopping the processing of a 
request that has already been started. 


These routines process I/O requests for both common and random access 
devices. They distinguish between categories based on the value of the 
NUM$BUFFERS field in the unit's device-unit information block (DUIB). 
(When calling each of these routines, the I/O System supplies a pointer 
to the DUIB as one of the parameters.) If the NUM$BUFFERS field is 
nonzero, the routines assume the device is a random access device. If 
the NUM$BUFFERS field is zero, the routines assume the device is a common 
device. 


In addition to the routines just described, the I/O System supplies an 
interrupt handler (interrupt service routine) and an interrupt task 
(called INLERRUPT$TASK) which respond to all interrupts generated by the 
units of a device, process those interrupts, and start the device working 
on the next I/O request on the queue. The INIT$IO procedure creates the 
interrupt task. 


After a device finishes processing a request, it sends an interrupt to 
the processor. As a consequence, the processor calls the interrupt 
handler. This handler either processes the interrupt itself or invokes 
an interrupt task to process the interrupt. Since an interrupt handler 
is limited in the types of system calls that it can make and the number 
of interrupts that can be enabled while it is processing, an interrupt 
task usually services the interrupt. The interrupt task feeds the 
results of the interrupt back to the I/0 System (data from a read 
operation, status from other types of operations). The interrupt task 
then gets the next I/O request from the queue and starts the device 
processing this request. This cycle continues until the device is 
detached. 
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Figure 3-1 shows the interaction between an interrupt task, an I/O 
device, an I/O request queue, and the Queue I/O device driver procedure. 
The interrupt task in this figure is in a continual cycle of waiting for 
an interrupt, processing it, getting the next I/O request, and starting 
up the device again. While this is going on, the Queue I/O procedure 
runs in parallel, putting additional I/0 requests on the queue. 





REQUEST QUEUE INTERRUPT TASK 


1/0 REQUEST 
1/0 REQUEST 


1/0 REQUEST 






SERVICE @ START DEVICE 


<r SS ® 
INTERRUPT 
<< 
‘ 


@ GET REQUEST 













DEVICE 


@ INTERRUPT 






QUEUE I/O PROCEDURE 


|r 
PUT REQUESTS ON QUEUE 


x-678 


Figure 3-1. Interrupt Task Interaction 


I/O SYSTEM ALGORITHM FOR CALLING THE DEVI.CE DRIVER PROCEDURES 


The I/O System calls each of the four device driver procedures in 
response to specific conditions. Figure 3-2 is a flow chart that 
illustrates the conditions under which three of the four procedures are 
called. The following numbered paragraphs discuss the portions of Figure 
3-2 labeled with corresponding circled numbers. 


1. To start I/O processing, an application task must make an I/O 
request. It can do this by invoking any of a variety of system 
calls. However, if you are an iRMX 86 user, the first I/O request to 
each device-unit must be an RQ$A$PHYSICAL$ATTACH$DEVICE system call, 
and if you are an iRMX 88 user, the first request to each device-unit 
must be either a DQ$ATTACH or a DQ$CREATE system call. 
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If the request results from an RQ$A$PHYSICAL$ATTACH$DEVICE, a 
DQ$ATTACH, or a DQ$CREATE system call, the I/O System checks to 
see if any other units of the device are currently attached. If 
no other units of the device are currently attached, the I/0 
System realizes that the device has not been initialized and calls 
the Initialize I/O procedure first, before queueing the request. 


Whether or not the I/O System called the Initialize I/0 procedure, 


it calls the Queue I/O procedure to queue the request for 
execution. 


If you are an iRMX 86 user and the request just queued resulted 
from an iRMX 86 RQ$A$PHYSICAL$DETACH$DEVICE system call, the 1/0 
System checks to see if any other units of the device are 
currently attached. If no other units of the device are attached, 
the I/O System calls the Finish I/O procedure to do any final 
processing on the device and clean up resources used by the device 
driver routines. 


If you are an iRMX 88 user and the request just queued resulted 
from either a DQ$DETACH or a DQ$DELETE system call, the I/O System 
checks to see if any other units of the device are currently 
attached. If no other units of the device are attached, the I/0 
System calls the Finish I/O procedure to do any final processing 
on the device and clean up resources used by the device driver 
routines. 


The iRMX 86 I/O System calls the fourth device driver procedure, the 
Cancel I/O procedure, under the following conditions: 


If the user makes an RQ$A$PHYSICAL$DETACH$DEVICE system call 
specifying the hard detach option, to forcibly detach the 
connection objects associated with a device-unit. The iRMX 86 
BASIC I/O SYSTEM REFERENCE MANUAL describes the hard detach 
option. 


If the job containing the task which made a request is deleted. 


The iRMX 88 I/O System does not call the Cancel I/O procedure. 
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THE USER MAKES AN I/O REQUEST 
VIA ASYSTEM CALL 











DOES THIS 
REQUEST RESULT FROM AN 
RQSASPHYSICALSATTACHSDEVICE 
SYSTEM CALL? OR FROM A 
DQSATTACH OR 
DQOS$CREATE SYSTEM CALL 


YES 




















ARE 
ANY UNITS 
OF THE DEVICE 
CURRENTLY 
ATTACHED 






YES 















1/0 SYSTEM CALLS THE 
INITIALIZE I/O PROCEDURE TO 
INITIALIZE THE DEVICE 








VO SYSTEM CALLS THE QUEUEI/O 
PROCEDURE TO PLACE THE 
REQUEST ON THE QUEUE 













DOES 
THIS REQUEST 
RESULT FROM AN 
RQSAS$PHYSICALS- 
DETACHSDEVICE 
SYSTEM CALL 






YES ® 















ARE 
ANY OTHER 
UNITS OF THE 
DEVICE CURRENTLY 
ATTACHED 






YES 
















1/0 SYSTEM CALLS THE FINISH I/O 
PROCEDURE TO CLEAN UP THE 
DEVICE AND DELETE OBJECTS 








RETURN 
1877 


Figure 3-2. How the I/O System Calls the Device Driver Procedures 
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REQUIRED DATA STRUCTURES 


In order for the I/O System-supplied routines to be able to call the 
user-supplied routines, you must supply the addresses of these 
user-supplied routines, as well as other information, in a Device 
Information Table. In addition, processing I/O requests through a random 
access driver requires a Unit Information Table. Each DUIB contains one 
pointer field for a Device Information Table and another for a Unit 
Information Table. 


DUIBs that correspond to units of the same device should point to the 
same Device Information Table, but they can point to different Unit 
Information Tables, if the units have different characteristics. Figure 
3-3 illustrates this. 











OuiB1 
Device 1 
Unit 0 















UNITSINFO$1 DEVSINFOS1 


DEVSINFO$1 


UNITSINFOS$1 





DEVSINFOS1 


UNITSINFO$2 


UNITSINFOS$2 


DEVSINFOS2 Es 


DEVSINFO$2 


UNITSINFO$2 


x-293 


Figure 3-3. DUIBs, Device and Unit Information Tables 
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DEVICE INFORMATION TABLE 


Common and random access Device Information Tables contain the same 
fields in the same order. When creating Device Information Tables for 
iRMX 86 applications, code them in the format shown here (as 
assembly-language structures). If you give the iRMX 86 ICU the pathname 
of your Unit Information Table file, the ICU includes the file in the 
assembly of IDEVCF.A86 (a Basic I/O System configuration file). 
IDEVCF.A86 contains the definition of the structure. 


The fields DEVICE$INIL, DEVICE$FINISH, DEVICE$START, DEVICE$STOP, and 
DEVICE$INTERRUPT contain the names of user-supplied procedures whose 
duties are described in Chapter 5. When creating the file containing 
your Device Information Tables, specify external declarations for these 
user~supplied procedures. This allows the code for these user-supplied 
procedures to be included into the assembly of the I/O System. For 
example, if your procedures are named DEVICE$INIT, DEVICE$FINISH, 
DEVICE$START, DEVICE$STOP, and DEVICE$INTERRUPI, include the following 
declarations in the file containing your Device Information Tables: 


extrn device$init: near 
extrn device$finish: near 
extrn device$start: near 
extrn device$stop: near 
extrn device$interrupt: near 


The iRMX 88 ICU prompts you for each field in the Device Information 


Table structure. The. iRMX 88 ICU generates the Device Information Table 
and places it in the device configuration source file. 


Use the following format when coding your Device Information Tables: 


RADEV_DEV_INFO < 


& LEVEL, ; word 
& PRIORITY, 3; byte 
& STACK$SIZE, ; word 
& DATA$SIZE, ; word 
& NUM$UNITS, ; word 
& DEVICE$INIT, ; word 
& DEVICE$FINISH, ; word 
& DEVICE$START, ; word 
& DEVICE$STOP, 3; word 
& DEVICE$ INTERRUPT 3; word 
& > 
where: 
LEVEL WORD specifying an encoded interrupt level at which 


the device will interrupt. The interrupt task uses 
this value to associate itself with the correct 
interrupt level. The values for this field are 
encoded as follows: 
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PRIORITY 


STACK$SIZE 


DATA$SIZE 


NUM$UNITS 


iRMX 86 VALUES 


Bits Value 
15-7 0 
6-4 First digit of the interrupt level 
(0-7). 
3 If one, the level is a master level and 
bits 6-4 specify the entire level 
number, 


If zero, the level is a slave level and 
bits 2-0 specify the second digit. 


2-0 Second digit of the interrupt level 
(0-7), if bit 3 is zero. 


iRMX 88 VALUES 


The values available are 0 through 3FH. Refer to 
the iRMX 88 REFERENCE MANUAL for further 
information. 


BYTE specifying the initial priority of the 
interrupt task. The actual priority of an 

iRMX 86 interrupt task might change because the 
iRMX 86 Nucleus adjusts an interrupt task's 
priority according to the interrupt level that it 
services. Refer to the iRMX 86 NUCLEUS REFERENCE 
MANUAL for further information about this 
relationship between interrupt task priorities 
and interrupt levels. 


WORD specifying the size, in bytes, of the stack 
for the user-written device interrupt procedure 
(and procedures that it calls). This number 
should not include stack requirements for the I/0 
System-supplied procedures. They add their 
requirements to this figure. 


WORD specifying the size, in bytes, of the user 
portion of the device's data storage area. This 
figure should not include the amount needed by 
the I/O System-supplied procedures; rather, it 
should include only that amount needed by the 
user-written routines. This then is the size of 
the read or write buffers plus any flags that the 
user-written routines need. 


WORD specifying the number of units supported by 


the driver. Units are assumed to be numbered 
consecutively, starting with zero. 
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DEVICE$ INIT WORD specifying the start address of a 
user-written device initialization procedure. 
The format of this procedure, which INIT$I0 


calls, is described in Chapter 5. 


DEVICE$FINISH WORD specifying the start address of a 


user-written device finish procedure. The format 
of this procedure, which FINISH$I0O calls, is 
described in Chapter 5. 


DEVICE$START WORD specifying the start address of a 
user-written device start procedure. The format 
of this procedure, which QUEUE$IO and 
INTERRUPT$TASK call, is described in Chapter 5. 


DEVICE$STOP WORD specifying the start address of a 
user-written device stop procedure. The format 
of this procedure, which CANCEL$IO calls, is 


described in Chapter 5. 


DEVICES INTERRUPT WORD specifying the start address of a 
user-written device interrupt procedure. The 
format of this procedure, which INTERRUPT$TASK 
calls, is described in Chapter 5. 


Depending on the requirements of your device, you can append additional 


information to the RADEV_DEV_INFO structure. For example, most devices 
require you to append the I/O port address to this structure, so that the 
user-written procedures have access to the device. 


UNTIL INFORMATION TABLE 


If you have random access device drivers in your system, you must create 
a Unit Information Table for each different type of unit in your system. 
Each random access device-unit's DUIB must point to one Unit Information 
Table, although multiple DUIBs can point to the same Unit Information 
Table. The Unit Information Table must include all information that is 


unit-dependent. 


When creating Unit Information Tables for iRMX 86 applications, code them 


in the format shown here (as assembly-language structures). If you give 
the iRMX 86 ICU the pathname of your Unit Information Table file, the ICU 
includes the file in the assembly of IDEVCF.A86 (a Basic I/0 System 


configuration file). IDEVCF.A86 contains the definition of the structure. 


The iRMX 88 ICU prompts you for some fields in the Unit Information Table 


structure. The iRMX 88 ICU generates the Unit Information Table and 
places it in the device configuration source file. 


The minimum requirements for the structure of the Unit Information Table 
are as follows: 
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RADEV_UNIT_INFO < 


&  ‘TRACK$SIZE, 
&  MAX$RETRY, 
&  CYLINDER$SIZE ; word 
& 


> 


where: 


TRACK$SIZE 


MAX$RETRY 


CYLINDER$SIZE 


; word 
3; word 


WORD specifying the size, in bytes, of a single track 
of a volume on the unit. If the device controller 
Supports reading and writing across track boundaries, 
and your driver is a random-access driver, place a 
zero in this field. If you specify a zero for this 
field, the I/O System-supplied random access support 
procedures place an absolute sector number in the 
DEV$LOC field of the I[ORS. If you specify a nonzero 
value for this field, the random access support 
procedures guarantee that read and write requests do 
not cross track boundaries. They do this by placing 
the sector number in the low-order word of the DEV$LOC 
field of the LORS and the track number in the 
high-order word of the DEV$LOC field before calling a 
user-written device start procedure. Instructions for 
writing a device start procedure are contained in 
Chapter 5. 


WORD specifying the maximum number of times an I/O 
request should be tried if an error occurs. Nine is 
the recommended value for this field. When this field 
contains a nonzero value, the I/O System-supplied 
procedures guarantee that read or write requests are 
retried if the user-supplied device start or device 
interrupt procedures return an IO$SOFT condition in 
the IORS.UNIT$STATUS field. (The LORS.UNIT$STATUS 
field is described in the "IORS Structure" section of 
Chapter 2.) 


For iRMX 86 systems, a WORD whose meaning depends on 
its value, as follows: 


0 The I/O System never requests a seek 


operation. Instead, it expects the device 
driver/controller to perform implied "seeks" 
when a read/write on the unit begins on a 
cylinder which is different from the one 
associated with the current position of the 
read/write head. 


1 The I/O System automatically requests a seek 
operation (to seek to the correct cylinder) 
before performing a read or write. The 


device driver for the unit must call the 
SEEK$COMPLETE procedure immediately 


following each seek operation. 
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Other Any other value specifies the number of 
sectors in a cylinder on the unit. The I/O 
System automatically requests a seek 
operation whenever a requested read or write 
operation om the unit begins in a different 
cylinder than that associated with the 
current position of the read/write head. 
The device driver for the unit must call the 
SEEK$COMPLETE procedure immediately 


following each seek operation. 


RELATIONSHIPS BETWEEN 1/0 PROCEDURES AND I/0 DATA STRUCTURES 


This section brings together several of the procedures and data 
structures that have been described so far in this manual. Figure 3-4 
shows the many relationships that exist among these entities, with solid 
arrows indicating procedure calls and dotted arrows indicating pointers. 
Note that the I/O System contains the address of each DUIB, which in turn 
contains the addresses of the procedures that the I/O System calls when 
performing I/O on the associated device-unit. The DUIB also contains the 
address of the Device Information Table and, if the device is a random 
access device, the Unit Information Table. The Device Information Table, 
in turn, contains the addresses of the procedures that are called by the 
procedures that the I/O System calls. It is through these links that the 
appropriate calls are made in the servicing of an I/O request for a 
particular device-unit. 
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Figure 3-4. Relationships Between I/O Procedures and L[/O Data Structures 





DEVICE DATA STORAGE AREA 


The common and random access device drivers are set up so that all data 


that is local to a device is maintained in an area of memory. The 
Initialize I/O procedure creates this device data storage area, and the 


other procedures of the driver access and update information in it as 


needed. Storing the device-local data in a central area serves two 
purposes. 


First, all device driver procedures that service individual units of the 


device can access and update the same data. The Initialize I/O procedure 
passes the address of the area back to the I/O System, which in turn 
gives the address to the other procedures of the driver. 
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They can then place information relevant to the device as a whole into 
the area. The identity of the first IORS on the request queue is 
maintained in this area, as well as the attachment status of the 
individual units and a means of accessing the interrupt task. 


Second, several devices of the same type can share the same device driver 
code and still maintain separate device data areas. For example, suppose 
two iSBC 204 devices use the same device driver code. The same 
Initialize I/O procedure is called for each device, and each time it is 
called it obtains memory for the device data. However, the memory areas 
that it creates are different. Only the incarnations of the routines 
that service units of a particular device are able to access the device 
data area for that device. 


Although the common and random access device drivers already provide this 


mechanism, you may want to include a device data storage area in any 
custom driver that you write. 


WRITING DRIVERS FOR USE WITH BOTH iRMX™ 86- AND iRMX™ 88-BASED SYSTEMS 
A common or random access device driver that makes no system calls is 
compatible with both the iRMX 86 and iRMX 88 I/O Systems. Consequently, 


such a device driver can be "ported" between applications based on the 
two iRMX systems. 


week 
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CHAPTER 4 
I/O REQUESTS 





This chapter contains two kinds of information that writers of drivers 
for devices other than terminals will find useful. Presented first are 
summaries of the actions that the I/O System takes in response to the 
various kinds of I/O requests that application tasks can make. Next are 


three tables -- one for each type of device driver -- that show which 
DUIB and IORS fields device drivers should be concerned with. 


I/O SYSTEM RESPONSES TO I/O REQUESTS 


This section shows which device driver procedures the I/O System calls 
when it processes each of the eight kinds of I/O requests. When there 
are multiple calls, the order of the calls is significant. 


ATTACH DEVICE REQUESTS 


When the I/O System receives the first attach device request for a 


device, it makes the following calls, in order, to device driver 
procedures: 


The Call The Effects of the Call 


Initialize I/0 The driver resets the device as a whole 


and creates the device data storage 
area and interrupt task(s). 


Queue 1/0, with the The driver resets the selected unit. 


FUNCT field of the IORS 
set to F$ATTACH (=4) 


When the I/O System receives an attach device request that is not the 
first for the device, it makes the following call: 
The Call The Effects of the Call 
Queue I/0, with the The driver resets the selected unit. 


FUNCT field of the IORS 
set to F$ATTACH (=4) 
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DETACH DEVICE REQUESTS 


When the I/O System receives a detach device request, and there is more 
than one unit of the device attached, it makes the following call: 


The Call The Effects of the Call 
Queue I/0, with the The driver performs cleanup operations 
FUNCT field of the IORS for the selected unit, if necessary. 


set to F$DETACH (=5) 


When the I/O System receives a detach device request, and there is only 


one attached unit on the device, it makes the following calls, in order, 
to device driver procedures: 


The Call Toe Effects of the Call 
Queue I/0, with the The driver performs cleanup operations 
FUNCT field of the IORS for the selected unit, if necessary. 


set to F$DETACH (=5) 


Finish 1/0 The driver performs cleanup operations 
for the device as a whole (if 
necessary) and deletes the objects 
created by Initialize I/0. 


READ, WRITE, OPEN, CLOSE, SEEK, AND SPECIAL REQUESTS 


When the I/O System receives a read, write, open, close, seek, or special 
request, it makes the following call to a device driver procedure: 


The Call The Effects of the Call 
Queue 1/0, with the FUNCT The driver performs the requested 
field of the IORS set to operation. (F$OPEN and F$CLOSE 


F$READ (=0), F$WRITE (=1), usually require no processing.) 
F$OPEN (=6), F$CLOSE (=7), 

F$SEEK (=2), or F$SPECIAL 

(=3), depending on the type 

of the I/O request. 


CANCEL REQUESTS 
When a connection is deleted while I/O might be in progress, such as when 


an iRMX 86 job is deleted, the I/O System makes the following calls, in 
order, to device driver procedures: 
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The Call The Effects of the Call 
Cancel 1/0 The driver removes from the request 


queue all requests that contain the 


same Cancel ID value as that in the 
current request, and stops processing 


if necessary. 


Queue I/O, with the When this request reaches the front of 

FUNCT field of the the queue, it is simply returned to the 
IORS set to F$CLOSE indicated response mailbox (exchange). 

(=7) 


DUIB AND [ORS FIELDS USED BY DEVICE DRIVERS 


Tables 4-1, 4-2, and 4-3 indicate, for each type of device driver, the 


fields of DUIBs and IORSs with which user-written portions of device 
drivers need to be concerned. 


Device Drivers 4-3 





I/O REQUESTS 


Table 4-1. DUIB and IORS Fields Used by Common Device Drivers 





_ i rR ny a “Pry re na ete tear 


Attach Detach 
Device Device Open Close Read Write Seek Special 


















































DUIB ; 

Name eines poe se eae es 
File$drivers | eesesesa—i‘(‘i‘iC;COC 

Functs eee eee Oaeke ae 

Flags no nm mom m m m m 
Dev$gran ee eee m m m m m m 
Dev$size m nh|)|)hCUuMS”~C«wM m m m m 
Device aera 2 nee a! 
Unit m m n mn nm Mm a ee 
Dev$unit Fae at ee tee oe Bee 

Init$io Se ae = 

Finish$io a ate oe SS nn ee See 
Queue$io eae eee oe en ne __. 
Cancel$io ane ee. eit ee neces a - = 
Device$info$p m m m mm =m am mem 
Unit$info$p | Sn nL | I m m 
Update$timeout se ete ek en ie ete z 
Num$buffers ee er a ere ree 

Priority Pos, Sete hoes Oe Se _ es 
Fixed$update eee 
Max$buffers Pe na he te ee wade ee, 
IORS 

Status W Ww W _ we W W W W 
Unit$status w wW Ww Ww w ew w SW eo! 
Actual eee ee, WwW W ee 
Actual$fill ace 

Device a ee Le EEE 

Unit m m nom m Tm re Sale 
Funct ER, eee AS Se, SOMERS RENEE S aaa een Ok 
Subfunct ps i aera 
Dev$loc rene. ae m m 

Buff$p Sea ee er r r ee 
Count ee eet 5 = 
Count$fill ead ee __ ae 
Aux$p Oe ee Oe naa eae 
Link$for Ei ES Seek a NL a a ee 
Link$back ee ae oe geen teen A ein eee 
Re sp$mbox Seen Eee re ee gee te ee ee 
Done Ww _ WwW ww ww _ Ww 
Fill tse Bot anes fn tt ee he ned __ ais 
Cancel$id aes SEs eer 
Conn$t 


r --- is read by the device driver 
w --- is written by the device driver 
m --- might be read by some device drivers 


nnn a a i ae i eI 
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Table 4-2. DUIB and IORS Fields Used by Random Access Device Drivers 


DUIB 
Name 
File$drivers 
Functs 
Flags 
Dev$gran 
Dev$size 
Device 
Unit 
Dev$unit 
Init$io 
Finish$io 
Queue$io 
Cancel$io 
Device$info$p 
Unit$info$p 
Update$timeout 
Num$buffers 
Priority 
Fixed$update 
Max$buffers 


TORS 

Status 
Unit$status 
Actual 

Ac tual$fill 
Device 
Unit 

Funct 
Subfunct 
Dev$loc 
Buff$p 
Count 
Count$fill 
Aux$p 
Link$for 
Link$back 
Resp$mbox 
Done 

Fill 
Cancel$id 
Conn$t 








ear een myth te A A ee se 


Attach Detach 
Device Device Open Close Read Write Seek Special 


ee NY ee a eS Ane te in ene AE 


rrr eee ta ee ene Nt tet tence tA a 








a a an ey At A ely ern =A e-em 




















n 
5 
ie) 
5 
5 
Le) 
ie) 
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i rn cer i see 


r--- is read by the device driver 
w --- is written by the device driver 
m -~- might be read by some device drivers 
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Table 4-3. DUIB and IORS Fields Used by Custom Device Drivers 


Attach Detach 
Device Device Open Close Read Write Seek Special 


DUIB 2 

Name 

File$drivers Se eee 

Functs . 

Flags m m nm m m m m 
Dev$gran m m nem m m m m 
Dev$size m m m _m m m m m 
Device . : 

Unit m m m m m m m m 
Dev$unit aaa 

Init$io . 

Finish$io . 

Queue$io 

Cancel$io : 

Device$info$p m m nm m m m m 
Unit$info$p m m mm m m m m 
Update$ timeout 

Num$buffers ; 

Priority ; 

Fixed$update : 

Max$buffers ; 

IORS 

Status W W W W Ww W Ww W 
Unit$status WwW Ww ww W W W W 
Actual W W 

Ac tual$fill 3 ; 

Device 5 

Unit m m m _m m m m m 
Funct r r r joe r C r r 
Subfunct | ; 

Dev$loc : m m m 

Buff$p : r r 

Count ; r r 

Count$fill : 

Aux$p . m 
Link$for a a a _a a a a a 
Link$back a a a _a a a a a 
Resp$mbox r r r - r r r r 
Done a a a _a a a a a 
Fill a a a a a a a a 
Cancel$id iM 


Conn$t 


r 
wo 
m 
a 





=== is read by the device driver 

is written by the device driver 

--- might be read by some device drivers 

--- is available for any purpose suiting the needs of the device 
driver 


tek 
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CHAPTER 5 
WRITING COMMON OR RANDOM 
ACCESS DEVICE DRIVERS 





This chapter contains the calling sequences for the procedures that you 
must provide when writing a common or random access device driver. Where 
possible, descriptions of the duties of these procedures accompany the 
calling sequences. 


In addition to providing information about the procedures that common or 
random access drivers must supply, this chapter describes the purpose and 
calling sequence for each of five procedures, two of which random access 
device drivers in iRMX 86 applications must call under certain conditions. 


INTRODUCTION TO PROCEDURES THAT DEVICE DRIVERS MUST SUPPLY 


The routines that are provided by the I/O System and that the L/O System 
calls (INIT$I0O, FINISH$IO, QUEUE$IO, CANCEL$10, and INTERRUPT$TASK for 
iRMX 86 systems) (RAD$INIT$IO, RAD$FINISH$IO, RAD$QUEUE$IO, 
RAD$CANCEL$10, and INTERRRUPT$TASK for iRMX 88 systems) constitute the 
bulk of a common or random access device driver. These routines, in 
turn, make calls to device-dependent routines that you must supply. 
These device-dependent routines are described here briefly and then are 
presented in detail: 


A device initialization procedure. This procedure must perform any 
initialization functions necessary to get the device ready to process 
I/O requests. INIT$IO calls this procedure. 


A device finish procedure. This procedure must perform any 


necessary final processing on the device so that the device can be 
detached. FINISH$IO calls this procedure. 


A device start procedure. This procedure must start the device 
processing any possible I/O function. QUEUE$IO and INTERRUPT$TASK 
(the I/O System-supplied interrupt task) call this procedure. 


A device stop procedure. This procedure must stop the device from 


processing the current I/O function, if that function could take an 
indefinite amount of time. CANCEL$IO calls this procedure. 


A device interrupt procedure. This procedure must do all of the 


device-dependent processing that results from the device sending an 
interrupt. INTERRUPT$TASK calls this procedure. 
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DEVICE INITIALIZATION PROCEDURE 


The INIT$IO procedure calls the user-written device initialization 
procedure to initialize the device. The format of the call to the 
user-written device initialization procedure is as follows: 


CALL device$init(duib$p, ddata$p, status$p); 


where: 


device$init Name of the device initialization procedure. You can 
use any name for this procedure, as long as it doesn't 
conflict with other procedure names and you include 
the name in the Device Information Table. 


duib$p POINTER to the DUIB of the device-unit being 
attached. From this DUIB, the device initialization 
procedure can obtain the Device Information Table, 


where information such as the I/O port address is 
stored. 


ddata$p POINTER to the user portion of the device's data 
storage area. You must specify the size of this 
portion in the Device Information Table for this 
device. The device initialization procedure can use 
this data area for whatever purposes it chooses. 
Possible uses for this data area include local flags 
and buffer areas. 


status$p POINTER to a WORD in which the device initialization 
procedure must return the status of the initialization 
operation. It should return the E$OK condition code 
if the initialization is successful; otherwise it 
should return the appropriate exceptional condition 
code. If initialization does not complete 
successfully, the device initialization procedure must 
ensure that any resources it creates are deleted. 


If you have a device that does not need to be initialized before it can 
be used, you can use the default device initialization procedure supplied 
by the I/O System. The name of this procedure is DEFAULT$INIT. Specify 
this name in the Device Information Table. DEFAULT$INIT does nothing but 
return the E$0K condition code. 


DEVICE FINISH PROCEDURE 


The FINISH$IO procedure calls the user-written device finish procedure to 
perform final processing on the device, after the last I/0 request has 
been processed. The format of the call to the device finish procedure is 
as follows: 


CALL device$finish(duib$p, ddata$p); 
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where: 


device$finish Name of the device finish procedure. You can use any 
name for this procedure, as long as it doesn't 
conflict with other procedure names and you include 
the name in the Device Information Table. 


duib$p POINTER to the DUIB of the device-unit being 
detached. From this DUIB, the device finish procedure 
can obtain the Device Information Table, where 
information such as the I/O port address is stored. 


ddata$p POINTER to the user portion of the device's data 
storage area. The device finish procedure should 
obtain, from this data area, identification of any 
resources other user-written procedures may have 
created, and delete these resources. 


If you have a device that does not require any final processing, you can 
use the default device finish procedure supplied by the I/O System. The 
name of this procedure is DEFAULT$FINISH. Specify this name in the 
Device Information Table. DEFAULT$FINISH merely returns control to the 


caller. It is normally used when the default initialization procedure 
DEFAULT$INIT is used. 


DEVICE START PROCEDURE 


Both QUEUE$1I0 and INTERRUPT$TASK make calls to the device start procedure 
to start an I/O function. QUEUE$IO calls this procedure on receiving an 
I/O request when the request queue is empty. INTERRUPT$TASK calls the 
device start procedure after it finishes one I/O request if there are one 
or more I/O requests on the queue. ‘The format of the call to the device 
start procedure is as follows: 


CALL device$start(iors$p, duib$p, ddata$p); 


where: 


device$start Name of the device start procedure. You can use any 
name for this procedure, as long as it doesn't 
conflict with other procedure names and you include 
the name in the Device Information Table. 


Lors$p POINTER to the IORS of the request. The device start 
procedure must access the IORS to obtain information 
such as the type of I/O function requested, the 
address on the device of the byte where I/O is to 
commence, and the buffer address. 
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duib$p POINTER to the DUIB of the device-unit for which the 


I/O request is intended. The device start procedure 
can use the DUIB to access the Device Information 
Table, where information such as the I/O port address 
is stored. 


ddata$p POINTER to the user portion of the device's data 


storage area. The device start procedure can use this 
data area to set flags or store data. 


The device start procedure must do the following: 


It must be able to start the device processing any of the 


functions supported by the device and recognize that requests for 
nonsupported functions are error conditions. 


If it transfers any data, it must update the IORS.ACTUAL field to 
reflect the total number of bytes of data transferred (that is, 


if it transfers 128 bytes of data, it must put 128 in the 
IORS.ACTUAL field). 


If an error occurs when the device start procedure tries to start 
the device (such as on an write request to a write-protected 
disk), the device start procedure must set the IORS.STATUS field 
to indicate an E$ILO condition and the IORS.UNIT$STATUS field to a 
nonzero value. The lower four bits of the field should be set as 
indicated in the "IORS Structure" section of Chapter 2. The 
remaining bits of the field can be set to any value (for example, 
the iSBC 204 device driver returns the device's result byte in 
the remainder of this field). I£ the function completes without 
an error, the device start procedure must set the IORS.STATUS 
field to indicate an E$0OK condition. 


If the device start procedure determines that the I/O request has 
been processed completely, either because of an error or because 
the request has completed successfully, it must set the IORS.DONE 
field to TRUE. The I/O request will not always be completed; it 
may take several calls to the device interrupt procedure before a 
request is completed. However, if the request is finished and 
the device start procedure does not set the IORS.DONE field to 
TRUE, the device driver support routines wait until the device 
sends an interrupt and the device interrupt procedure sets 
IORS.DONE to TRUE, before determining that the request is 
actually finished. 


DEVICE STOP PROCEDURE 


The CANCEL$IO procedure calls the user-written device stop procedure to 
stop the device from performing the current I/O function. The format of 
the call to the device stop procedure is as follows: 
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CALL device$stop(iors$p, duib$p, ddata$p) ; 


where: 

device$stop Name of the device stop procedure. You can use any 
name for this procedure, as long as it doesn't 
conflict with other procedure names and you include 
this name in the Device Information Table. 

lors$p POINTER to the [ORS of the request. The device stop 
procedure needs this information to determine what 
type of function to stop. 

duib$p POINTER to the DUIB of the device-unit on which the 
I/O function is being performed. 

dda ta$p POINTER to the user portion of the device's data 


storage area. The device stop procedure can use this 
area to store data, if necessary. 


If you have a device which guarantees that all I/O requests will finish 
in an acceptable amount of time, you can omit writing a device stop 
procedure and use the default procedure supplied with the I/0 System. 
The name of this procedure is DEFAULT$STOP. Specify this name in the 
Device Information Table. DEFAULT$STOP simply returns to the caller. 


DEVICE INTERRUPT PROCEDURE 


INTERRUPT$TASK calls the user-written device interrupt procedure to 
process an interrupt that just occurred. The format of the call to the 
device interrupt procedure is as follows: 


CALL device$interrupt(iors$p, duib$p, ddata$p); 


where: 


device$interrupt Name of the device interrupt procedure. You can 
use any name for this procedure, as long as it 
doesn't conflict with other procedure names and 


you include this name in the Device Information 
Table. 


Llors$p POINTER to the IORS of the request being 
processed. The device interrupt procedure must 
update information in this IORS. A value of zero 
for this parameter indicates either that there 
are no requests on the request queue and the 
interrupt is extraneous or that the unit is 
completing a seek or other long-term operation. 


duib$p POINTER to the DUIB of the device-unit on which 
the I/O function was performed. 
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ddata$p POINTER to the user portion of the device's data 
storage area. The device interrupt procedure can 
update flags in this data area or retrieve data 
sent by the device. 


The device interrupt procedure must do the following: 


® It must determine whether the interrupt resulted from the 
completion of an I/O function by the correct device-unit. 


@ If the correct device-unit did send the interrupt, the device 
interrupt procedure must determine whether the request is 


finished. If the request is finished, the device interrupt 
procedure must set the IORS.DONE field to TRUE. 


e It must process the interrupt. ‘This may involve setting flags in 
the user portion of the data storage area, tranferring data 
written by the device to a buffer, or some other operation. 


e If an error has occurred, it must set the IORS.STATUS field to 
indicate an E$I0O condition and the IORS.UNIT$STATUS field to a 
nonzero value. The lower four bits of the field should be set as 
indicated in the "IORS Structure" section of Chapter 2. The 
remaining bits of the field can be set to any value (for example, 
the iSBC 204 and 206 device drivers return the device's result 
byte in the remainder of this field). It must also set the 
IORS.DONE field to TRUE, indicating that the request is finished 
because of the error. 


e If no error has occurred, it must set the IORS.STATUS field to 
indicate an E$OK condition. 


PROCEDURES THAT iRMX™ 86 RANDOM ACCESS DRIVERS MUST CALL 


There are several procedures that random access drivers in iRMX 86 
applications can call under certain well--defined circumstances. They are 
NOTIFY, SEEK$COMPLETE, and procedures for the long-term operations 
(BEGIN$LONG$TERM$OP, END$LONG$TERM$OP, and GET$IORS). 


NOTIFY PROCEDURE 


Whenever a door to a flexible diskette drive is opened or the STOP button 
on a hard disk drive is pressed, the device driver for that device must 
notify the I/O System that the device is no longer available. The device 
driver does this by calling the NOTIFY procedure. When called in this 
manner, the I/O System stops accepting I/O requests for files on that 
device unit. Before the device unit can again be available for I/0 
requests, the application must detach it by a call to 
A$PHYSICAL$DETACH$DEVICE and reattach ft by a call to 
A$PHYSICAL$ATTACH$DEVICE. Moreover, the application must obtain new file 
connections for files on the device unit. 
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In addition to not accepting I/O requests for files on that device unit, 
the I/O System will respond by sending an object to a mailbox. For this 
to happen, however, the object and the mailbox must have been established 
for this purpose by a prior call to A$SPECIAL, with the spec$func 
argument equal to FS$NOTIFY (2). (The A$SPECIAL system call is described 
in the BASIC I/O SYSTEM REFERENCE MANUAL.) The task that awaits the 
object at the mailbox has the responsibility of detaching and reattaching 
the device unit and of creating new file connections for files on the 
device unit. 


The syntax of the NOTIFY procedure is as follows: 


CALL NOTLIFY(unit, ddata$p); 


where: 
unit BYTE containing the unit number of the unit on the 
device that went off-line. 
ddata$p POINTER to the user portion of the device's data 


storage area. This is the same pointer that is passed 
to the device driver by way of either the device$start 
or the device$interrupt procedure. 


SEEK$COMPLETE PROCEDURE 


In most applications, it is desirable to overlap seek operations (which 


can take relatively long periods of time) with other operations. To 
facilitate this, a device driver receiving a seek request can take the 
following actions in the following order: 


l. The device start procedure starts the requested seek operation. 


2. Depending on the kind of device, either the device start 


procedure or the device interrupt procedure sets the DONE flag in 
the LORS to TRUE (OFFH). 


e Some devices send only one interrupt in response to a seek 
request -- the one that indicates the completion of the 
seek. If your device operates in this manner, the device 
start procedure sets the DONE flag to TRUE (OFFH) immediately. 


® Some devices send two interrupts in response to a seek 
request -- one upon receipt of the request and one upon 
completion of the seek. If your device operates in this 
manner, the device start procedure leaves the DONE flag in 
the IORS set to FALSE (0). 


When the first interrupt from the device arrives, the device 
interrupt procedure sets the DONE flag to TRUE (OFFH). 
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3. When the interrupt from the device arrives (the one that 
indicates the completion of the seek), the device interrupt 
procedure calls the SEEK$COMPLETE procedure to signal the 
completion of the seek operation, 


This process enables the device driver to handle I/O requests for other 
units on the device while the seek is in progress, thereby increasing the 
performance of the I/O System. 


The syntax of the call to SEEK$COMPLETE is as follows: 


CALL SEEK$COMPLETE(unit, ddata$p) 3 


where: 
unit BYfE containing the number of the unit on the device 
on which the seek operation is completed. 
ddata$p POINTER to the user portion of the device's data 


storage area. This is the same pointer that the 
random access support routines passes to the device 
start and device interrupt procedures. 


Note that if your device driver calls the SEEK$COMPLETE procedure when a 
seek operation is completed, the CYLINDER$SIZE field of the Unit 
Information Table for the device unit should be configured greater than 
zero. On the other hand, if the driver does not call SEEK$COMPLETE, then 
CYLINDER$SIZE must be configured to zero. 


PROCEDURES FOR OTHER LONG-TERM OPERATIONS 


The iRMX 86 Operating System provides three procedures which device 
drivers can use to overlap long-term operations (such as tape rewinds) 
with other I/O operations. The procedures are BEGIN$LONG$TERM$OP, 
END$LONG$TERM$OP, and GET$IORS. These procedures are intended 
specifically for use with devices that do not support seek operations 
(such as tape drives). 


BEGIN$LONG$TERM$OP Procedure 


The BEGIN$LONG$TERM$OP procedure informs the random access support 
routines that a long-term operation is in progress, and that the support 
routines do not have to wait for the operation to complete before 
servicing other units on the device. Calling BEGIN$LONG$TERM$0P allows 
the controller to service read and write requests on other units of the 
device while the long-term operation is in progress. 
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To use BEGIN$LONG$TERM$OP, the device driver receiving the request for 
the long-term operation should take the following actions: 


1. The 


device start procedure starts the long-term operation. 


2. Depending on the kind of device, either the device start 
procedure or the device interrupt PEOCeaUEE sets the DONE flag in 


the 


3. The 


IORS to TRUE (OFFH). 


Some devices send only one interrupt in response to a request 


for a long-term operation ~- the one that indicates the 
completion of the operation. If your device operates in this 


manner, the device start procedure sets the DONE flag to TRUE 
(OFFH) immediately. 


some devices send two interrupts in response to a request for 
a long-term operation -- one upon receipt of the request and 
one upon completion of the operation. If your device 
operates in this manner, the device start procedure leaves 
the DONE flag in the [ORS set to FALSE (0). When the first 
interrupt from the device arrives, the device interrupt 
procedure sets the DONE flag to TRUE (OFFH). 


procedure that just set the DONE flag to TRUE (either the 


device start or device interrupt procedure) calls 
BEGIN$LONG$TERM$OP. 


The syntax of the call to BEGIN$SLONG$TERM$0P is as follows: 


CALL BEGIN$LONG$TERM$0P(unit, ddata$p) ; 


where: 


unit 


ddata$p 


BYTE containing the number of the unit on the device 
which is performing the long-term operation. 


POINTER to the user portion of the device's data 
storage area. This is the same pointer that the 
random access support routines passes to the device 
start and device interrupt procedures. 


If your driver calls BEGIN$LONG$TERM$OP, it must also call 
END$LONG$TERM$OP when the device sends an interrupt to indicate the end 
of the long-term operation. 


END$LONG$TERM$0P Procedure 


The END$LONG$TERM$0P procedure informs the random access support routines 


that a long-term operation has completed. A driver that calls 
BEGIN$LONG$TERM$OP must also call END$LONG$TERM$OP or the driver cannot 
further access the unit that performed the long-term operation. 
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Specifically, when the unit sends an interrupt indicating the end of the 
long-term operation, the device interrupt procedure must call 
ENDSLONGSTERMSOP. 

The syntax of the call to ENDSLONGSTERMSOP is as follows: 


CALL ENDSLONGSTERMSOP(unit, ddata$p); 


where: 
unit BYTE containing the number of the unit on the device 
which performed the long-term operation. 
ddataSp POINTER to the user portion of the device's data 


storage areae This is the same pointer that the 
random access support routines passes to the device 
start and device interrupt procedures. 


GETSIORS Procedure 


Long-term operations on some units involve multiple operations. For 
example, performing a rewind on some tape drives requires you to perform 
a rewind and a read file mark. The GETSIORS procedure allows your driver 
procedures to handle this situation without forcing you to write a custom 
driver for each device that is different, 


GETSIORS allows your driver procedure to obtain the token of the IORS for 
the previous long-term request, so that it can modify the IORS to 
initiate new I/O requests. The IORSSP that INTERRUPTSTASK passed to the 
device interrupt procedure is set to zero (for units busy performing a 
seek or other long-term operation). Therefore, the driver can only 
access the IORS in this mannere 


To use GETSIORS, the device driver performing the long-term operation 
should take the following actions: 


1. The device driver starts the long-term operation and calls 
BEGINSLONGSTERMSOP in the usual manner (as described in the 
“BEGINSLONGSTERMSOP Procedure" section). 

2. When the unit sends an interrupt indicating the end of the 
long-term operation, the device interrupt procedure calls 
GETSIORS to obtain the IORS. 

3. The device interrupt procedure modifies the FUNCT and SUBFUNCT 
fields of the IORS to specify the next operation to perform It 
also sets the DONE flag to FALSE (0). 

4. The device interrupt procedure calls ENDSLONGSTERMSOPERATION. 

The syntax of the call to GETSIORS is as follows: 


forsSbase = GETSIORS(unit, ddataSp); 
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where: 

lors$base SELECTOR in which the random access support 
routines return the base portion of the IORS. 
Use the PL/M-86 built-in procedure BULLD$PTR 
(specifying an offset of 0) to obtain a pointer 
to the IORS. 

unit BYTE containing the number of the unit on the 
device which performed the long-term operation. 

ddata$p POINTER to the user portion of the device's data 


storage area. This is the same pointer that the 
random access support routines passes to the device 
start and device interrupt procedures. 


FORMATTING CONSIDERATIONS 


If you write a random access driver and you intend to use the Human 
Interface FORMAT command (for iRMX 86 systems) or the RQ$FORMAT call (for 
iRMX 88 systems) to format volumes on that device, your driver routines 
must set the status field in the IORS in the manner that the FORMAT 
command expects. 


When formatting volumes, the FORMAT command issues system calls 


(A$SPECIAL or S$SPECIAL) to format each track. It knows that formatting 
is complete when it receives an E$SPACE exception code in response. To 


be compatible with FORMAT, your driver must also return E$SPACE. 


In particular, if your driver must perform some operation on the device 


to format it, your device interrupt procedure must set the IORS.STATUS to 
E$SPACE after the last track has been formatted. 


However, if the device requires no physical formatting (for example, when 
formatting is a null operation for that device), your device start 


procedure can set IORS.STATUS to E$SPACE immediately after being called 
to start the formatting operation. 


tekek 
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CHAPTER 6 
2 WRITING A CUSTOM 
DEVICE DRIVER 


Custom device drivers are drivers that you create in their entirety 
because your device doesn't fit into either the common or random access 
device category, either because the device requires a priority-ordered 
queue, multiple interrupt levels, or because of some other reasons that 
you have determined. When you write a custom device driver, you must 
provide all of the features of the driver, including creating and 
deleting resources, implementing a request queue, and creating an 
interrupt handler. You can do this in any manner that you choose as long 
as you supply the following four procedures for the I/O System to call: 


An Initialize I/O Procedure. This procedure must initialize the 


device and create any resources needed by the procedures in the 
driver. 


A Finish I/O Procedure. This procedure must perform any final 
processing on the device and delete resources created by the 
remainder of the procedures in the driver. 


A Queue I/O Procedure. This procedure must place the I/O requests on 
a queue of some sort, so that the device can process them when it 
becomes available. 


A Cancel I/O Procedure. This procedure must cancel a previously 
queued I/O request. 


In order for the I/O System to communicate with your device driver 
procedures, you must provide the addresses of these four procedures for 
the DUIBs that correspond to the units of the device. 


The next four sections describe the format of each of the I/O System 
calls to these four procedures. Your procedures must conform to these 
formats. 


INITIALIZE I/O PROCEDURE 


The £RMX 86 I/O System calls the Initialize I/O procedure when an 
application task makes an RQ$A$PHYSICAL$ATTACH$DEVICE system call and no 
units of the device are currently attached. The iRMX 88 I/O System calls 
the Initialize I/O procedure when an application task attaches or creates 
a file on the device and no other files on the device are currently 
attached. In either case, the I/O System calls the Initialize 1/0 
procedure before calling any other driver procedure. 
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The Initialize I/O procedure must perform any initial processing 
necessary for the device or the driver. If the device requires an 
interrupt task (or region or device data area, in the case of iRMX 86 
drivers), the Initialize I/O procedure should create it (them). 


The format of the call to the Initialize I/O procedure is as follows: 


CALL init$io(duib$p, ddata$p, status$p); 


where: 


init$io Name of the Initialize I/O procedure. You can use any 
name for this procedure as long as it does not 
conflict with other procedure names. You must, 
however, provide its starting address in the DUIBs of 
all device-units that it services. 


duib$p POINTER to the DUIB of the device-unit for which the 
request is intended. The init$io procedure uses this 
DUIB to determine the characteristics of the unit. 


ddata$p POINTER to a WORD in which the init$io procedure can 
place the location of a data storage area, if the 
device driver needs such an area. If the device 
driver requires that a data area be associated with a 
device (to contain the head of the I/O queue, DUIB 
addresses, or status information), the init$io 
procedure should create this area and save its 
location via this pointer. If the driver does not 
need such a data area, the init$io procedure should 
return a zero via this pointer. 


status$p POINTER to a WORD in which the init$io procedure must 
place the status of the initialize operation. If the 
operation is completed successfully, the init$io 
procedure must return the E$OK condition code. 
Otherwise it should return the appropriate exception 
code. If the init$io procedure does not return the 
E$OK condition code, it must delete any resources that 
it has created. 


FINISH I/O PROCEDURE 


The 1RMX 86 I/O System calls the Finish I/O procedure after an 
application task makes an RQ$A$PHYSICAL$DETACH$DEVICE system call to 
detach the last unit of a device. The iRMX 88 I/O System calls the 
Finish I/O procedure when an application task detaches or deletes the 
last remaining file connection for the device. 


The Finish I/O procedure performs any necessary final processing on the 
device. It must delete all resources created by other procedures in the 
device driver and must perform final processing on the device itself, if 
the device requires such processing. 
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The format of the call to the Finish I/O procedure is as follows: 


CALL finish$io(duib$p, ddata$t); 


where: 


finish$io Name of the Finish I/O procedure. You can specify 
any name for this procedure as long as it does not 
conflict with other procedure names. You must, 
however, provide its starting address in the DUIBs 
of all device-units that it services. 


duib$p POINTER to the DUIB of the device-unit of the 
device being detached. The finish$io procedure 
needs this DUIB in order to determine the device on 
which to perform the final processing. 


ddata$t SELECTOR containing the location of the data 
storage area originally created by the init$io 
procedure. The finish$io procedure must delete 
this resource and any others created by driver 
routines. 


QUEUE 1/0 PROCEDURE 


The I/O System calls the Queue I/O procedure to place an I/O request on a 
queue, so that it can be processed when the device is not busy. The 
Queue I/O procedure must actually start the processing of the next I/O 
request on the queve if the device is not busy. The format of the call 
to the Queue I/O procedure is as follows: 


CALL queue$io(iors$t, duib$p, ddata$t); 


where: 
queue$io Name of the Queue I/0 procedure. You can use any 
name for this procedure as long as it does not 
conflict with other procedure names. You must, 
however, provide its starting address for the DUIBs 
of all device-units that it services. 
iors$t SELECTOR containing the location of an IORS. This 


IORS describes the request. When the request is 
processed, the driver (though not necessarily the 
queue$io procedure) must fill in the status fields 
and send the IORS to the response mailbox 
(exchange) indicated in the IORS. Chapter 2 
describes the format of the IORS. It lists the 
information that the I/O System supplies when it 
passes the IORS to the queue$io procedure and 
indicates the fields of the IORS that the device 
driver must fill in. 
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duib$p POINTER to the DUIB of the device-unit for which 
the request is intended. 


ddata$t SELECTOR containing the location of the data 
storage area originally created by the init$io 
procedure. The queue$io procedure can place any 
necessary information in this area in order to 
update the request queue or status fields. 


CANCEL I/O PROCEDURE 


The I/O System can call the Cancel I/0 procedure in order to cancel one 
or more previously queued I/O requests. The iRMX 88 I/O System does not 
call Cancel I/0, but in the iRMX 86 environment Cancel I/O is called 
under either of the following two conditions: 


@ If the user makes an RQ$A$PHYSICAL$DETACH$DEVICE system call and 
specifies the hard detach option (refer to the iRMX 86 BASIC I/0 
SYSTEM REFERENCE MANUAL for a description of this call). This 
system call forcibly detaches all objects associated with a 
device-unit. 


® If the job containing the task which made an I/O request is 
deleted. The I/O System calls the Cancel I/O procedure to remove 
any requests that tasks in the deleted job might have made. 


If the device cannot guarantee that a request will be finished within a 
fixed amount of time (such as waiting for input from a terminal 
keyboard), the Cancel I/O procedure must actually stop the device from 
processing the request. If the device guarantees that all requests 
finish in an acceptable amount of time, the Cancel I/O procedure does not 
have to stop the device itself, but only removes requests from the queue. 


The format of the call to the Cancel I/O procedure is as follows: 


CALL cancel$io(cancel$id, duib$p, ddata$t); 


where: 
cancel$id Name of the Cancel I/O procedure. You can use any 
name for this procedure as long as it doesn't 
conflict with other procedure names. You must, 
however, provide its starting address in the DUIBs of 
all device-units that it services. 
cancel$id WORD containing the id value for the I/O requests 


that are are to be cancelled. Any pending requests 
with this value in the cancel$id field of their 
TORS's must be removed from the queue of requests by 
the Cancel I/O procedure. Moreover, the I/O System 
places a CLOSE request with the same cancel$id value 
in the queue. The CLOSE request must not be 
processed until all other requests with that 
cancel$id value have been returned to the I/0 System. 
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duib$p POINTER to the DUIB of the device-unit for which 
the request cancellation is intended. 


ddata$t SELECTOR containing the location of the data 
storage area originally created by the init$io 
procedure. This area may contain the request queue. 


IMPLEMENTING A REQUEST QUEUE 


Making I/O requests via system calls and the actual processing of these 
requests by I/O devices are asynchronous activities. When a device is 
processing one request, many more can be accumulating. Unless the device 
driver has a mechanism for placing I/O requests on a queue of some sort, 
these requests will become lost. The common and random access device 
drivers form this queue by creating a doubly linked list. The list is 
used by the QUEUE$IO and CANCEL$IO procedures, as well as by 
INTERRUPT$TASK. 


Using this mechanism of the doubly linked list, common and random access 
device drivers implement a FIFO queue for I/O requests. If you are 
writing a custom device driver, you might want to take advantage of the 
LINK$FOR and LINK$BACK fields that are provided in the IORS and implement 
a scheme similar to the following for queuing I/O requests. 


Each time a user makes an I/O request, the I/O System passes an IORS for 
this request to the device driver, in particular to the Queue I/0 
procedure of the device driver. The common and random access driver 
Queue I/O procedures make use of the LINK$FOR and LINK$BACK fields of the 
IORS to link this IORS together with IORSs for other requests that have 
not yet been processed. 


This queue is set up in the following manner. The device driver routine 
that is actually sending data to the controller accesses the first IORS 
on the queue. The LINK$FOR field in this IORS points to the next IORS on 
the queue. The LINK$FOR field in the second IORS points to the third 
IORS on the queue, and so forth until, in the last IORS on the queue, the 
LINK$FOR field points back to the first IORS on the queue. The LINK$BACK 
fields operate in the same manner. The LINK$BACK field of the last IORS 
on the queue points to the previous IORS. The LINK$BACK field of the 
second to last IORS points to the third to last IORS on the queue, and so 
forth, until, in the first IORS on the queue, the LINK$BACK field points 
back to the last IORS in the queue. A queue of this sort is illustrated 
in Figure 6-l. 


The device driver can add or remove requests from the queue by adjusting 
LINK$FOR and LINK$BACK pointers in the IORSs. 
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Figure 6-1. Request Queue 


To handle the dual problems of locating the queue and ascertaining 
whether the queue is empty, you can use a variable such as head$queue. 
If the queue is empty, head$queue contains the value 0. Otherwise, 
head$queue contains the address of the first IORS in the queue. 


REE 
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CHAPTER 7 
TERMINAL DRIVERS 





Both the iRMX 86 and iRMX 88 Operating Systems supply a Terminal Handler 
that can serve as an interface between the Nucleus and a terminal 

device. This interface is minimal and allows limited interaction between 
the terminal operator and the Operating System. However, the iRMX 86 
Operating System also provides an interface to terminals via the Basic 
I/O System. This interface allows tasks to use the power and convenience 
of I/O System calls when communicating with terminals. To add support 
for new terminal controllers in the Basic I/O System, you can write 
device drivers, which provide the software link between the Operating 
System software (called the Terminal Support Code) and the terminal. 


The iRMX 88 Executive does not support terminal drivers as outlined in 
this chapter. 


This chapter explains how to write a terminal driver whose capabilities 
include handling single-character I/0, parity checking, answering and 
hanging up functions on a modem, and automatic baud rate searching for 
each of several terminals. Such a driver is neither common, random 
access, nor custom. Consequently, this chapter is more self-contained 
than Chapters 5 and 63 it describes the data structures used by terminal 
drivers, as well as the procedures that you must provide. 


TERMINAL SUPPORT CODE 


As in the case of common and random access drivers, the I/O System 
provides the procedures that the I/O System invokes when performing 


terminal I/O. They are known collectively as the Terminal Support Code. 
Figure 7-1 shows schematically the relationships between the various 


layers of code that are involved in driving a terminal. 


Among the duties performed by the Terminal Support Code are managing 
buffers and maintaining several terminal-related modes. 
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Figure 7-1. Software Layers Supporting Terminal I/0 


DATA STRUCTURES SUPPORTING TERMINAL I/0 


The principal data structures supporting terminal I/O are the Device-Unit 
Information Block (DUIB), Device Information Table, Unit Information 
Table, and the Terminal Support Code (TSC) data structure. These data 
structures are defined in the next few paragraphs. 


DUIB 


This section lists the elements that make up a DUIB for a device-unit 
that is a terminal. When creating DUIBs for iRMX 86 applications, code 
them in the format shown here (as assembly-language structures). If you 
give the iRMX 86 ICU the pathname of your Unit Information Table field, 
the iRMX 86 Interactive Configuration Utility (ICU) includes your DUIB 
file in the assembly of IDEVCF.A86 (a Basic I/O System configuration 
file). IDEVCF.A86 contains the definition of the structure. 
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DEFINE DUIB < 
& NAME, ; byte (14) 
& l, ; word - file$drivers - (physical) 
&  OFBH, ; byte - functs —- (no seek) 
& O, ; byte - flags - (not disk) 
& Os ; word - dev$gran - (not random access) 
& O, ; dword -— dev$size - (not storage device) 
& DEVICE, 3 byte - (device dependent) 
& UNIT, 3; byte — (unit dependent) 
&  DEV$UNIT, ; word - (device and unit dependent) 
&  TSINITIO, ; word - init$io - (terminal device) 
&  TSFINISHIO, ; word - finish$io - (terminal device) 
&  TSQUEUEIO, ; word - queue$io - (terminal device) 
&  TSCANCELIO, ; word — cancel$io - (terminal device) 
&  DEVICE$INFO$P, 3; pointer - (address of 

3 TERMINAL$DEVICE$ INFO) 
&  UNIT$INFO$P, ; pointer - (address of 

; TERMINAL$UNIT$ INFO) 
&  OFFFFH, 3; word -— update$timeout - (not disk) 
& QO, ; word — num$buffers - (none) 
& PRIORITY, 3; byte - (1/0 System dependent) 
& O, ; byte — fixed$update - (none) 
& O, 3; byte - max$buffers - (none) 
& RESERVED, 3; byte 
& > 


DEVICE INFORMATION TABLE 


A terminal's Device Information Table provides information about a 
terminal controller. When creating these tables, code them in the format 
shown here (as assembly-language declarations). If you give the iRMX 86 
ICU the pathname of your Unit Information Table field, the ICU includes 
the — in the assembly of IDEVCF.A86 (a Basic I/0 System configuration 
file). 


The fields TERM$INIT, TERM$FINISH, TERM$SETUP, TERM$OUT, TERM$ANSWER, 
TERM$HANGUP, and TERM$CHECK contain the names of user-supplied procedures 
whose duties are described later in this chapter. When creating the file 
containing your Device Information Tables, specify external declarations 
for these user~supplied procedures. This allows the code for these 
user-supplied procedures to be included in the generation of the I/0 
System. For example, if your procedures are named TERM$INIT, 
TERM$FINISH, TERM$SETUP, TERM$OUI, TERM$ANSWER, TERM$HANGUP, and 
TERM$CHECK, include the following declarations in the file containing 
your Device Information Tables: 


extrn term$init: near 
extrn term$finish: near 
extrn term$setup: near 
extrn term$out: near 
extrn term$answer: near 
extrn term$hangup: near 
extrn term$check: near 
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Use the following format when coding your Device Information Tables: 


TERMINAL$DEVICE$ INFORMATION 

DW NUMS$UNITS 

DW DRIVER$DATA$SIZE 

DW STACK$SIZE 

DW TERM$INIT 

DW ‘THERM$FINISH 

DW TERM$SETUP 

DW LERM$SOUTL 

DW ‘TERM$ANSWER 

DW TERM$HANGUP 

DW NUM$INTERRUPTS 

INTERRUPTS 

DW INTERRUPT$LEVEL 
DW TERM$CHECK 
‘ ; define interrupt$level and 
. ; term$check for each interrupt 

° ; level 
DRIVER$ INFO 

DB DRIVER$ INFO$1 

DB DRIVER$INFO$2 


where: 


NUM$UNITS WORD containing the number of terminals on this 
terminal controller. 


DRIVER$DATA$S IZE WORD containing the number of bytes in the 
driver's data area pointed to by the 
USER$DATA$PTR field of the TSC Data structure. 


STACK$SIZE WORD containing the number of bytes of stack 
needed collectively by the user-supplied 
procedures in this device driver. 


TERM$ INIT WORD specifying the address of this controller's 
user-written terminal initialization procedure. 
When creating the Device Information Table, use 
the procedure name as a variable to supply this 
information. 


TERM$F INISH WORD specifying the address of this controller's 
user-written terminal finish procedure. When 
creating the Device Information Table, use the 


procedure name as a variable to supply this 
information. 


TERM$SETUP WORD specifying the address of this controller's 
user-written terminal setup procedure. When 
creating the Device Information Table, use the 


procedure name as a variable to supply this 
information. 
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NUMS$ INTERRUPTS 


INTERRUPT $LEVEL 


TERM$CHECK 


DRIVER$ INFO 
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WORD specifying the address of this controller's 
user-written terminal output procedure. When 
creating the Device Information Table, use the 
procedure name as a variable to supply this 
information. 


WORD specifying the address of this controller's 
user-written terminal answer procedure. When 
creating the Device Information Table, use the 
procedure name as a variable to supply this 
information. 


WORD specifying the address of this controller's 
user-written terminal hangup procedure. When 
creating the Device Information fable, use the 


procedure name as a variable to supply this 
information. 


WORD containing the number of interrupt lines 
that this controller uses. You must define an 
INTERRUPT$LEVEL and TERM$CHECK word for each 
interrupt. 


WORDs containing the level numbers of the 
interrupts that are associated with the terminals 
driven by this controller. You must supply one 
such word for each interrupt the controller uses. 


WORDs specifying the addresses of this 
controller's user-written terminal check 
procedures. Each TERM$CHECK field specifies the 
terminal check procedure for the INTERRUPT$LEVEL 
immediately preceding it. When creating the 
Device Information Table, use the procedure names 
as the variables to supply this information. If 
any of the TERM$CHECK words equals zero, there is 
no term$check procedure associated with the 
corresponding interrupt level. Instead, 
interrupts on these levels are assumed to be 
output ready interrupts which will cause TERM$0UT 
to be called. 


BYTES or WORDS containing driver-dependent 
information. 
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NOTE 


Usually, terminal drivers are concerned 
only with the DRIVER$INFO fields of the 
Device Information Table. Therefore, a 
terminal driver can declare a structure 


of the following form when accessing 
this data: 


DECLARE 
TERMINAL$DEVICES$ INFO STRUCTURE( 
FILLER(nbr$of$words) WORD, 


DRIVER$INFO$1 BYTE, 
DRIVERS INFO$2 BYTE, 
DRIVER$ INFO$N BYTE) ; 


where nbr$of$words equals 10 + 


2*(number of interrupt levels used by 
the driver) 


You must supply the TERM$INIT, TERM$FINISH, TERM$SETUP, TERM$OUT, 
TERM$ANSWER, TERM$HANGUP, and TERM$CHECK procedures. However, if your 
terminals are not used with modems, the TERM$ANSWER and TERM$HANGUP 
procedures can simply contain a RETURN. Also, if your application does 
not need to perform special processing when all of the terminals on the 
controller are detached, the TERM$FINISH procedure also can simply 
contain a RETURN. 


UNIT INFORMATION TABLE 


A terminal's Unit Information Table provides information about an 
individual terminal. Although only one Device Information Table can 
exist for each driver (controller), several Unit Information Tables can 
exist if different terminals have different characteristics (such as baud 
rate, duplex, or parity, for example). When creating Unit Information 
Tables, code them in the format shown here (as assembly-language 
declarations). If you give the iRMX 86 ICU; the pathname of your Unit 
Information Table field, the ICU includes the file in the assemgly of 
IDEVCF.A86 (a Basic I/O System configuration file). 
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TERMINAL$UNIT$ INFORMATION 


DW 
DW 
DW 
DW 
DW 
DW 
DW 
DW 
DW 
DW 


CONN$FLAGS 
TERM$FLAGS 
IN$RATE 
OUT$RATE 
SCROLL$NUMBER 
FLOW$CONTROL* 
HIGH$WATER$MARK* 
LOW$WATER$MARK* 
FC$ON$CHAR* 
FC$OFF$CHAR* 


*These elements apply only to buffered device drivers and are useful 
only if you must specify them at configuration time. 


where: 


CONN$FLAGS WORD s 


this t 


pecifying the default connection flags for 
erminal. Refer to the iRMX 86 BASIC I/O 


SYSTEM REFERENCE MANUAL for more information 


about 
follow 


Bits 


0-1 


these flags. The flags are encoded as 
s. (Bit 0 is the low-order bit.) 


Value and Meaning 


Line editing control. 


O = Invalid Entry. 

1 = No line editing (transparent mode). 
2 = Line editing (normal mode). 

3 = No line editing (flush mode). 


Echo control. 


0 Echo. 


l Do not echo. 


Input parity control. 


0 Set parity bit to 0. 


1 


Do not alter parity bit. 
Output parity control. 
QO = Set parity bit to 0. 


1 = Do not alter parity bit. 
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Bits Value and Meaning 
5 Output control character control. 


0 = Accept output control characters in the 
input stream. 


1 = Ignore output control characters in the 
input stream. 


6-7. OSC control sequence control. 


O = Act upon OSC sequences that appear in 
either the input or output stream. 


1 = Act upon OSC sequences in the input 
stream only. 


2 = Act upon OSC sequences in the output 
stream only. 


3 = Do not act upon any OSC sequences. 


8-15 Reserved bits. For future compatibility, 
set to 0. 


TERM$F LAGS WORD specifying the terminal connection flags for 
this terminal. Refer to the iRMX 86 BASIC I/O 
SYSTEM REFERENCE MANUAL for more information 
about these flags. The flags are encoded as 
follows. (Bit 0 is the low-order bit.) 


Bits Value and Meaning 
0 Reserved bit. Set to l. 
1 Line protocol indicator. 
0 = Full duplex. 
1 = Half duplex. 
2 Output medium. 
0 = Video display terminal (VDT). 
1 = Printed (Hard copy). 
3 Modem indicator. 


O = Not used with a modem. 


1 = Used with a modem. 
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4-5 


6-8 


10 
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Value and Meaning 


Input parity control. 


QO = 


1 = 


Always set parity bit to 0. 
Never alter the parity bit. 


Even parity is expected on input. Set 
the parity bit to 0 unless the received 
byte has odd parity or there is some 
other error, such as (a) the received 
stop bit has a value of 0 (framing 
error) or (b) the previous character 
received has not yet been fully 
processed (overrun error.) 


Odd parity is expected in input. Set 
the parity bit to 0 unless the received 
byte has even parity or there is some 
other error, such as (a) the received 
stop bit has a value of 0 (framing 
error) or (b) the previous character 
received has not yet been fully 
processed (overrun error.) 


Output parity. control. 


0 = 


> 
li 


Always set parity bit to 0. 
Always set parity bit to l. 


Set parity bit to give the byte even 
parity. 


Set parity bit to give the byte odd 
parity. 


Do not alter the parity bit. 


Translation control. 


Do not enable translation. 


Enable translation. 


Terminal axes sequence control. This 
specifies the order in which Cartesian-like 
coordinates of elements on a terminal's 
screen are to be listed or entered. 


0 = 


List or enter the horizontal coordinate 
first. 
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Bits Value and Meaning 


ll 


13-1 


If bits 
6-8 als 


1 = List or enter the vertical coordinate 
first. 


Horizontal axis orientation control. This 
specifies whether the coordinates on the 


terminal's horizontal axis increase or 
decrease as you move from left to right 
across the screen. 


0 


Coordinates increase from left to right. 


1 


Coordinates decrease from left to right. 


Vertical axis orientation control. This 


specifies whether the coordinates on the 
terminal's vertical axis increase or 


decrease as you move from top to bottom 
across the screen. 


0 


Coordinates increase from top to bottom. 


1 


Coordinates decrease from top to bottom. 


5 Reserved bits. For future compatibility, 
set to 0. 


NOTE 


4-5 contain 2 or 3, and bits 
o contain 2 or 3, then they must 


both contain the same value. That is, 


they mu 


st both reflect the same parity 


convention (even or odd). 


WORD indicating the input baud rate. The word is 
encoded as follows: 

0 = Invalid. 

l= Perform an automatic baud rate search. 
Other = Actual input baud rate, such as 9600. 
WORD indicating the output baud rate. The word 
is encoded as follows: 

0 = Use the input baud rate for output. 
Other = Actual output baud rate, such as 9600. 
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Most applications require the input and output 
baud rates to be equal. In such cases, use 
IN$RATE to set the baud rate and specify a zero 
for OUT$RATE. 


SCROLL$ NUMBER WORD specifying the number of lines that are to 
be sent to the terminal each time the operator 


enters the appropriate control character 
(Control-W is the default). 


The Unit Information Table can contain additional data, depending on the 
needs of the controller. Refer to the “Additional Information for 
Buffered Devices" section of this chapter for information about other 
fields you can add to the table. 


TERMINAL SUPPORT CODE (TSC) DATA AREA 


DUIBs, Device Information Tables, and Unit Information Tables are 
structures that you set up at configuration time to provide information 


about the initial state of your terminals. During configuration, the ICU 
assembles these tables into the code segment of the Basic I/O System. 


Therefore, they remain fixed throughout the life of the application 
system. 


However, the Basic I/0 System also provides a structure in the data 


segment (this section calls it the TSC Data Area) which changes to 
reflect the current state of the terminal controller and its units. 


The TSC Data Area consists of three portions: 


e A 30H-byte controller portion which contains information that 
applies to the device as a whole. 


e A 400H-byte unit portion for each unit in the device. The 
NUM$UNITS field in the Device Information Table specifies the 
number of unit portions that the Basic I/O System creates. 


e A user portion which the user-written driver routines can use in 
any manner they choose. The DRIVER$DATA$SIZE field in the 
Device Information Table specifies the length of this portion. 
One of the fields in the controller portion (USER$DATA$PTR) 
points to the beginning of this field. 


Figure 7-2 illustrates the TSC Data Area graphically. 
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TSCSDATA 


UNITSDATAS1 


400H bytes 


| 
| 
| 


UNITSDATAS$N 


400H bytes 


USERSDATA 





1874 


Figure 7-2. TSC Data Area 


When the Basic I/O System calls one of your user-written driver 


procedures, it passes, aS a parameter, a pointer either to the start of 
the TSC Data Area or to the start of one of the unit portions of the TSC 
Data Area. Your driver routines can then obtain information from the TSC 
Data Area or modify the information there. 


The TSC Data Area always starts on a segment boundary Its structure is 
as follows: 
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DECLARE TSC$DATA STRUCTURE( 


IOS$DATA$S EGMENT SELECTOR , 
STATUS WORD, 
INTERRUPT$TYPE BYTE, 
INTERRUPT ING$UNIT BYTE, 
DEV$INFO$PTR POINTER , 
USER$DATA$PTR POINTER, 
RESERVED( 34) BYTE, 
DECLARE UNIT$DATA(*) STRUCTURE( 
UNIT$INFO$SPTR POINTER, 
TERMINAL$FLAGS WORD , 
IN$RATE WORD, 
OUT$RATE WORD, 
SCROLL$NUMBER WORD, 
RESERVED1(901) BYTE, 
BUF FERED $DEVICE$DATA( 11) BYTE, 
RESERVED2 (100) BYTE) 5 
where: 

T0S$DATA$SEGMENT SELECTOR containing the base address of the I/O 
System's data segment. The I/O System's terminal 
support routine TSINITIO fills in this 
information during initialization. 

STATUS WORD in which the user-written terminal 
initialization procedure must return status 
information. 

INTERRUPT$TYPE BYTE in which the user-written terminal check 
procedure must return the encoded interrupt 
type. The possible values are: 

0 None 

1 Input interrupt 

2 Output interrupt 

3 Ring interrupt 

4 Carrier interrupt 

5 Delay interrupt 
If the terminal check procedure detects that 
there are more interrupts to service, the 
terminal check procedure adds the following value: 

8 More interrupts 
to the encoded interrupt type it returns. 
For more information about these codes and their 
values, see the description of the terminal check 
procedure in the next section. 

INTERRUPTING$UNIT BYTE in which the user-written terminal check 


procedure must return the unit number of the 
interrupting device. This value identifies the 
unit that is interrupting. 
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POINTER to the Terminal Device Information Table 
for this controller. The I/O System's terminal 
support routine TSINITIO fills in this data 
during initialization. 


POINTER to the beginning of the user portion of 
the TSC Data Area. This user area can be used by 
the driver, as needed. The I/O System's terminal 
support routine TSINITIO fills in this pointer 
value during initialization. 


STRUCTUREs containing unit portions of the TSC 
Data Area. There is one structure for each unit 
(terminal) of the device. When a user attaches 
the unit (via the A$PHYSICAL$ATTACH$DEVICE system 
call or the ATTACHDEVICE Human Interface command, 
for example), the I/O System's terminal support 
routines initialize the appropriate UNIT$DATA 
structure. They perform the initialization by 
filling in all the fields of the UNIT$DATA 
Structure with information from the DUIB and the 
Unit Information Table. 


POINTER to the Unit Information Table for this 
terminal. This is the same information as in the 
UNIT$INFO$P field of the DUIB for this 
device-unit (terminal). 


WORD specifying the connection flags for this 
terminal. Refer to the iRMX 86 BASIC I/O SYSTEM 
REFERENCE MANUAL for more information about these 
flags. The flags are encoded as follows. (Bit 0 
is the low-order bit.) 


Bits Value and tleaning 
0 Reserved bit. Set to l. 
1 Line protocol indicator. 


O = Full duplex. 


1 = Half duplex. 
2 Output medium. 
0 = Video display terminal (VDT). 
1 = Printed (Hard copy). 
3 Modem indicator. 
0 = Not used with a modem. 
1 = Used with a modem. 
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Value and Meaning 


Input parity control. 


O= 


1 = 


Always set parity bit (bit 7) to 0. 
Never alter the parity bit. 


Even parity is expected on input. Set 
the parity bit to 0 unless the received 
byte has odd parity or there is some 
other error, such as (a) the received 
stop bit has a value of 0 (framing 
error) or (b) the previous character 
received has not yet been fully 
processed (overrun error.) 


Odd parity is expected in input. Set 
the parity bit to 0 unless the received 
byte has even parity or there is some 
other error, such as (a) the received 
stop bit has a value of 0 (framing 
error) or (b) the previous character 
received has not yet been fully 
processed (overrun error.) 


Output parity control. 


Q= 


1 = 


Always set parity bit to 0. 
Always set parity bit to l. 


Set parity bit to give the byte even 
parity. 


Set parity bit to give the byte odd 
parity. 


Do not alter the parity bit. 


Translation control. 


Do not enable translation. 


Enable translation. 


Terminal axes sequence control. This 
specifies the order in which Cartesian-like 
coordinates of elements on a terminal's 
screen are to be listed or entered. 


Os 


List or enter the horizontal coordinate 
first. 


Device Drivers 7-15 


IN$RATE 


OUT$RATE 


TERMINAL DRIVERS 


Bits Value and Meaning 


1 = List or enter the vertical coordinate 
first. 


ll Horizontal axis orientation control. This 
specifies whether the coordinates on the 
terminal's horizontal axis increase or 
decrease as you move from left to right 
across the screen. 


0 = Coordinates increase from left to right. 
1 = Coordinates decrease from left to right. 
12 Vertical axis orientation control. This 


specifies whether the coordinates on the 
terminal's vertical axis increase or 


decrease as you move from top to bottom 
across the screen. 


0 Coordinates increase from top to bottom. 


1 


Coordinates decrease from top to bottom. 


13-15 Reserved bits. For future compatibility, 
set to 0. 


NOTE 


If bits 4-5 contain 2 or 3, and bits 
6-8 also contain 2 or 3, then they must 
both contain the same value. That is, 


they must both reflect the same parity 
convention (even or odd). 


WORD indicating the input baud rate. The word is 
encoded as follows: 


0 = Invalid. 


li 


1 Perform an automatic baud rate search. 
Other = Actual input baud rate, such as 9600. 


WORD indicating the output baud rate. The word 
is encoded as follows: 


0 = Use the input baud rate for output. 


Other = Actual output baud rate, such as 9600. 
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Most applications require the input and output 
baud rates to be equal. In such cases, use 
IN$RATE to set the baud rate and specify a zero 
for OUT$RATE. 


SCROLL$NUMBER WORD specifying the number of lines that are to 
be sent to the terminal each time the operator 


enters the appropriate control character 
(Control-W is the default). 


BUFFERED$DEVICE$- BYTES that contain additional information that 

DATA applies to drivers of buffered devices 
(intelligent communications processors that 
maintain their own internal memory buffers). 
Refer to the “Additional Information for Buffered 
Devices" section to see how to access these bytes. 


PROCEDURES THAT TERMINAL DRIVERS MUST SUPPLY 


The routines that make up the Basic I/O System's Terminal Support Code 
constitute the bulk of the terminal device driver. These routines, in 
turn, make calls to device-dependent routines that you must supply. The 
following paragraphs describe the routines briefly. Sections that follow 
describe the routines in more detail. 


A terminal initialization procedure. ‘This procedure must perform any 


initialization functions necessary to get the terminal controller 
ready to process I/O requests. TSINITIO calls this procedure. 


A terminal finish procedure. This procedure must perform any final 
processing so that the terminal controller can be detached. 
TSFINISHIO calls this procedure. 


A terminal setup procedure. This procedure sets up the terminal in 


the proper mode (baud rate, parity, etc.). TSQUEUEIO and the 
Terminal Support Code's interrupt task call this procedure. 


A terminal answer procedure. This procedure sets the Data Terminal 
Ready (DTR) line for modem support. TSQUEUEIO and the Terminal 
Support Code's interrupt task call this procedure. 


A_terminal hangup procedure. This procedure clears the Data Terminal 
Ready (DIR) line for modem support. TSQUEUEIO and the Terminal 
Support Code's interrupt task call this procedure. 


A terminal check procedure. ‘This procedure determines which terminal 
sent an interrupt signal and what type of interrupt it is. The 
Terminal Support Code's interrupt handler calls this procedure. 


A terminal output procedure. This procedure displays a character at 


a terminal. TSQUEUEIO and the Terminal Support Code's interrupt task 
call this procedure. 


Device Drivers 7-17 


TERMINAL DRIVERS 


A_set output waiting procedure. This procedure signals the Terminal 


Support Code that a terminal is ready to perform character 
transmission and interrupt handling. 


When the Terminal Support Code calls these procedures, it passes, as a 


parameter, a pointer to the TSC Data Area described in the previous 
section. If the called procedure is to perform duties on behalf of all 
of the terminals connected to the controller, the Terminal Support Code 
passes a pointer to the beginning of the TSC Data Area (the device 
portion). On the other hand, if the procedure is to perform duties for 


just a particular terminal, the Terminal Support Code passes a pointer to 
the unit portion of the TSC Data Area that corresponds to the terminal. 


Because the TSC Data Area always starts on a paragraph boundary, a 
procedure that receives a pointer to a unit portion of the data area can 
construct a pointer to the beginning of the TSC Data Area. It does this 
by calling the PL/M-86 builtin procedure BUILD$PTR using the base part of 
the pointer it received and an offset of 0. Also, if a procedure, such 
as term$check, receives a pointer to the beginning of the TSC data area, 
it can calculate where any unit portion of the data area starts by using 
the following formula: 


unit$data$p = base(of TsC data area):[30H + (unit number * 400H) ] 


TERMINAL INITIALIZATION PROCEDURE 


This procedure must initialize the controller. The nature of this 
initialization is device-dependent. When finished, the terminal 
initialization procedure must fill in the STALUS field of the TSC Data 
Area, as follows: 


e If initialization is successful, it must set STATUS to E$0OK (0). 


6 If initialization is not successful, it should normally set 


STATUS equal to E$IO (2BH). However, it can set the STATUS field 
to any other value, in which case the Basic 1/0 System returns 
that value to the task that is attempting to attach the device. 
(The Human Interface ATTACHDEVICE command expects the procedure 
to return the E$IO status if initialization is unsuccessful.) 


The syntax of a call to the user-written terminal initialization 
procedure is as follows: 


CALL term$init(tsc$data$ptr) ; 
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where: 
term$init Name of the terminal initialization procedure. 
You can use any name for this procedure, as long 
as it doesn't conflict with other procedure names 
and you include the name in the Device 
Information Table. 
tsc$data$ptr POINTER to the beginning of the TSC Data Area. 


TERMINAL FINISH PROCEDURE 


The Terminal Support Code calls this procedure when a user detaches the 
last terminal unit on the terminal controller. ‘The terminal finish 
procedure can simply do a RETURN, it can clean up data structures for the 
driver, or it can clear the controller. The syntax of a call to the 
user-written terminal finish procedure is as follows: 


CALL term$finish(tsc$data$ptr) ; 


where: 
term$finish Name of the terminal finish procedure. You can 
use any name for this procedure, as long as it 
doesn't conflict with other procedure names and 
you include the name in the Device Information 
Table. 
tsc$data$ptr POINTER to the beginning of the TSC Data Area. 


TERMINAL SETUP PROCEDURE 


This procedure “sets up" one terminal according to the TERMINAL$FLAGS, 
IN$RATE, OUT$RATE, SCROLL$NUMBER, and BUFFERED$DEVICE$DATA fields in the 
corresponding UNIT$DATA portion of the TSC Data Area. In particular, if 
IN$RATE is 1, then the term$setup procedure must start a baud rate 
search. (The terminal check procedure usually finishes the search and 
then fills in IN$RATE with the actual baud rate.) If OUT$RATE is 0, the 
terminal setup procedure assumes the output baud rate is the same value 
as the input baud rate. 


If your terminal controller is a buffered device (an intelligent device 


that manages its own internal data buffers), the terminal setup procedure 
must also set one of the reserved fields of the UNIT$DATA structure. 
Refer to the “Buffered Devices” section in this chapter for more 
information. 


If your terminal driver supports a modem, the terminal setup procedure 


might have to perform additional services. Refer to the "Terminal 
Hangup" section for more information. 
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The terminal setup procedure must call the set output waiting procedure. 


Refer to a later section in this chapter for more information on the set 
output waiting procedure. The syntax of a call to the user-written 


terminal setup procedure is as follows: 


CALL term$setup(unit$data$n$ptr) ; 


where: 
term$setup Name of the terminal setup procedure. You can 
use any name for this procedure, as long as it 
doesn't conflict with other procedure names and 
you include the name in the Device Information 
Table. 
unit$data$n$ptr POINTER to the terminal's UNIT$DATA structure in 


the TSC Data Area. 


TERMINAL ANSWER PROCEDURE 


This procedure activates the Data Terminal Ready line for a particular 


terminal. The Terminal Support Code calls the terminal answer procedure 
only when both of the following conditions are true: 


e Bit 3 of TERMINAL$FLAGS in the terminal's UNIT$DATA structure 
(the modem indicator) is set to l. 


e The Terminal Support Code has received a Ring Indicate signal 
(the phone is ringing) or an answer request (via an OSC modem 
answer sequence) for the terminal. Refer to the iRMX 86 BASIC 
I/O SYSTEM REFERENCE MANUAL for more information about OSC 
sequences. 


The syntax of a call to the user-written terminal answer procedure is as 
follows: 


CALL term$answer(unit$data$n$p) ; 


where: 
term$answer Name of the terminal answer procedure. You can 
use any name for this procedure, as long as it 
doesn't conflict with other procedure names and 
you include the name in the Device Information 
Table. 
unit$data$n$p POINTER to the terminal's UNI'L$DATA structure in 


the TSC Data Area. 
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TERMINAL HANGUP PROCEDURE 


This procedure clears the Data Terminal Ready line for a particular 


terminal. The Terminal Support Code calls the terminal hangup procedure 
only when both of the following are true: 


e Bit 3 of TERMINAL$FLAGS in the terminal's UNIT$DATA structure 
(the modem indicator) is set to l. 


e The Terminal Support Code has received a Carrier Loss signal (the 
phone is hung up) or a hangup request (via an OSC modem hangup 


sequence) for the terminal. Refer to the iRMX 86 BASIC 1/0 
SYSTEM REFERENCE MANUAL for more information about OSC sequences. 


The syntax of a call to the user-written terminal hangup procedure is as 
follows: 


CALL term$hangup(unit$data$n$p) ; 


where: 
terms hangup Name of the terminal hangup procedure. You can 
use any name for this procedure, as long as it 
doesn't conflict with other procedure names and 
you include the name in the Device Information 
Table. 
unit$data$n$p POINTER to the terminal's UNIT$DATA structure in 


the Terminal Support Code data Area. 


NOTE 


Some modem devices recognize only 
carrier detect as an indication that 
someone is calling and loss of carrier 
detect as an indication of hangup. 
However, most of these devices require 
the Data Terminal Ready line to be 
active before they can recognize 
carrier detect. For these devices, the 
terminal setup procedure must activate 
the Data Terminal Ready line. 

Likewise, the terminal hangup procedure 
must clear the Data Terminal Ready line 
and then reactivate it. 
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TERMINAL CHECK PROCEDURE 


The Terminal Support Code calls this procedure whenever an interrupt 
occurs, which usually signals that a key on that terminal's keyboard has 
been pressed. When called, the terminal check procedure should determine 
the kind of interrupt and the interrupting unit, as follows: 


l. Check all terminals on the device for an input character. 


2. If no input character is available, check for a transmitter ready 
to send another character. 


3. If no transmit character is available, check for a change in 
status (such as a ring or carrier interrupt). 


When the terminal check procedure finds the first valid interrupt, it 
should quit scanning other units. Then i.t should place the unit number 
of the interrupting unit in the INTERRUPLING$UNIT field of the TSC Data 
Area and information about the type of interrupt in the INTERRUPT$TYPE 
field. The Terminal Support Code interprets values in the INTERRUPT$TIYPE 
field as follows: 


no interrupt 
input interrupt 
output interrrupt 
ring interrupt 
carrier interrupt 
delay interrupt 


MW PW He © 


Also, if the terminal check procedure detects another interrupt while it 
is returning information about the first interrupt, it should add the 
following value: 


8 more interrupts 


to the value it places in the INTERRUPT$TYPE field. Adding this value 


signals the Terminal Support Code to call. the terminal check procedure 
again after it processes the current interrupt. 


Unless the controller hardware guarantees that an additional interrupt 
will be set after one of multiple pending interrupts is serviced, the 
terminal check procedure should always signal that more interrupts are 
available unless it cannot detect interrupts at all. That is, it should 
always return one of the following values in the INTERRUPT$TYPE field: 


OH no interrupt 

9H input interrupt plus more 
OAH output interrupt plus more 
OBH ring interrupt plus more 
OCH carrier interrupt plus more 
ODH delay interrupt plus more 
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By returning these values, the terminal check procedure ensures that the 


Terminal Support Code calls it again. Otherwise, the driver could lose 
characters. If, in fact, there are no more interrupts to service, the 


terminal check procedure can return a zero value (no interrupt) the last 
time it is called. 


If your terminal driver supports a baud rate search to determine the baud 


rate of an individual terminal, the terminal check procedure must 
ascertain the terminal's baud rate, as follows: 


1. The first time the terminal check procedure encounters an input 
interrupt for a particular terminal, it should examine the 


IN$RATE field of that terminal's UNIT$DATA structure to determine 
the baud rate. 


2. If the IN$RATE field is set to 1 (perform automatic baud rate 


search), the terminal check procedure should examine the input 
character to determine if it is an uppercase "U". (It can 
usually check for 19200, 9600, and 4800 baud in one attempt.) 


3. If the terminal check procedure determines the baud rate, it 
should set the IN$RATE field of the UNIT$DATA structure to 
reflect the actual input baud rate. 


4. If the terminal check procedure cannot determine the baud rate, 
it should increment the IN$RATE field in the UNIT$DATA 
structure. When the next input interrupt occurs, the terminal 
check procedure can try again to determine the baud rate. Refer 
to the example terminal driver in Appendix B to see how to 
implement a baud rate scan. 


5. Place a value of ODH in the INTERRUPT$TYPE field (delay interrupt 
plus more). The ODH value tells the Terminal Support Code that a 
baud rate scan is in progress. The Terminal Support Code then 
waits a few clock cycles and calls the terminal setup procedure 
to “set up” the terminal for the new baud rate. 


If the terminal check procedure encounters an input interrupt, it must 
also return the input character to the procedure that called it, 
adjusting the parity bit according to bits 4 and 5 of the TERMINAL$FLAGS 
field in the interrupting unit's UNIT$DATA structure. If the interrupt 
is not an input interrupt, the terminal check procedure can return any 
value. 


The syntax of the call to the user-written terminal check procedure is as 
follows: 


input$char = term$check( tsc$data$ptr) 


where: 


input$char BYTE in which the terminal check procedure 
returns the input character, if the interrupt was 
an input interrupt. If the interrupt was not an 
input interrupt, this parameter can have any 
value. 
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term$check Name of the terminal check procedure. You can 


use any name for this procedure, as long as it 
doesn't conflict with other procedure names and 


you include the name in the Device Information 
Table. 


tsc$data$ptr POINTER to the start of the Terminal Support Code 
Data Area. 


TERMINAL OUTPUT PROCEDURE 


The Terminal Support Code calls this procedure to display a character at 
a terminal. The Terminal Support Code passes it the character and a 
pointer to the terminal's UNIT$DATA structure. If bits 6 through 8 of 
the TERMINAL$FLAGS field of the UNIT$DATA structure so indicate, the 
terminal output procedure should adjust the character's parity bit and 
then output the character to the terminal. 


The syntax of the call to the user-written terminal output procedure is 
as follows: 


CALL term$out(unit$data$n$p, output$character) ; 


where: 

term$out Name of the terminal output procedure. You can 
use any name for this procedure, as long as it 
doesn't conflict with other procedure names and 
you include the name in the Device Information 
Table. 

unit$data$n$p POINTER to the terminal's UNIT$DATA structure in 
the TSC Data Area. 

output$character BYTE containing a character that the terminal 


output procedure should send to the terminal. 


SET OUTPUT WAITING PROCEDURE 


This procedure notifys the Terminal Support Code that the particular 
terminal is ready to perform data transmission. 


The syntax of a call to the set output waiting procedure is as follows: 


CALL xts$set$output$waiting (unit$data$n$p) ; 
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xts$set$output 
$waiting 


unit$data$n$ptr 
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Name of the Terminal Support Code provided 


procedure. The terminal setup procedure 

that you write must declare 
xts$set$output$waiting as an external procedure 
with one pointer parameter. 


POINTER to the terminal's UNIT$DATA structure in 
the TSC Data Area, This si the same pointer 
passed to the terminal setup procedure by the 
Terminal Support Code. 


ADDITIONAL INFORMATION FOR BUFFERED DEVICES 


If you are writing a driver for a buffered communications device (an 
intelligent communications processor like the iSBC 544 board that manages 


its own buffers of data 


separately from the ones managed by the Terminal 


Support Code), your driver routines must make use of the 
BUFFERED$DEVICE$DATA fields of the UNIT$DATA structure. In so doing, 
they should impose the following structure on those 11 bytes: 


DECLARE BUFFERED$DEVICE$DATA STRUCTURE( 


BUFFERED$DEVICE 
FLOW$CONTROL 
HIGH$WATER$MARK 
LOW$WATER$MARK 
FC$ON$CHAR 
FCS$OFF$CHAR 


where: 


BUF FERED$DEVICE 


FLOW$CONTROL 


HIGH$WATER$MARK 


BYTE, 
WORD, 
WORD, 


WORD, 
WORD, 


WORD) ; 


When true, a BYT# that specifies whether the unit 
requires handling as a buffered device. 


WORD specifying whether the communications board 
sends flow control characters (selected by the 
FC$ON$CHAR and FC$OFF$CHAR fields, but usually 
XON and XOFF) to turn input on and off. The 


low-order bit (bit 0) controls this option, as 
follows: 


0 Disable flow control. 
1 Enable flow control. 


When flow control is enabled, the communication 
board can control the amount of data sent to it 
to prevent buffer overflow. 


When the communication board's input buffer fills 
to contain the number of bytes specified in this 


WORD, the board sends the flow control character 
to stop input. 
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LOW$WATER$MARK When the number of bytes in the communication 
board's input buffer drops to the number 
specified in this WORD, the board sends the flow 
control character to start input. 


FC$ON$CHAR WORD specifying an ASCII character that the 
communication board sends to the connecting 
device when the number of bytes in its buffer 
drops to the low-water mark. Normally this 
character tells the connecting device to resume 
sending data. 


FC$OFF$CHAR A WORD specifying an ASCII character that the 
communication board sends to the connecting 
device when the number of characters in its 
buffer rises to the high-water mark. Normally 
this character tells the connecting device to 
stop sending data. 


When a user attaches a unit on any terminal device, the Terminal Support 
Code calls the terminal setup procedure. If the device is a buffered 
device, the terminal setup procedure must set the BUFFERED$DEVICE field 
to TRUE (OFFH). It should also fill in the other fields of the 
BUFFERED$DEVICE$DATA structure. In addition, it should enable the 


communication device's on-board receiver interrupt (the one for the unit 
being attached) so that it can accept data from the connected terminal. 


When a user detaches a unit on a buffered device, the Terminal Support 
Code sets the BUFFERED$DEVICE field to FALSE (OH) and again calls the 
terminal setup procedure. The terminal setup procedure should disable 

the communication device's on-board receiver interrupt (the one for the 
unit being detached) to prevent extraneous characters from being received. 


To distinguish between an “attach device" and a “detach device", the 


terminal setup procedure should establish its own internal flags (one for 
each unit) in addition to the BUFFERED$DEVICE fields. It can use these 


flags as follows: 


1. Initially, the terminal initialization procedure sets the flag of 
each unit to FALSE to indicate that no devices are attached. 


2. When the Terminal Support Code calls the terminal setup procedure 
to attach a unit, both the BUFFERED$DEVICE field and the internal 
flag are FALSE. The terminal setup procedure recognizes from 
this combination that the operation is an "attach device.” 


3. The terminal setup procedure performs the “attach device" 
operations and sets the internal flag and the BUFFERED$DEVICE 
flag to TRUE to indicate that the device is attached. 


4, When the unit is detached, the Terminal Support Code sets the 
BUFFERED$DEVICE flag to FALSE and calls the terminal setup 
procedure. In this situation, the BUFFERED$DEVICE field is 
FALSE, but the internal flag is TRUE. The terminal setup 
procedure recognizes from this combination that the operation is 
a "detach device." 
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PROCEDURES' USE OF DATA STRUCTURES 


Table 7-1 helps you sort out the responsibilities of the various 


procedures in a terminal device driver. In the table, the following 
codes refer to those procedures: 


(1) terminal initialization 
(2) terminal finish 

(3) terminal setup 

(4) terminal answer 

(5) terminal hangup 

(6) terminal check 

(7) terminal output 


Also, "System" and "ICU" are used in Table 7-1 to indicate the iRMX 86 
software and the iRMX 86 Interactive Configuration Utility, 
respectively. In addition, “Term$flags" is an abbreviation of 


“Terminal$flags," and numbers following immediately after "Term$flags" 
are bit numbers in that word. 
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Table 7-1. Uses of Fields in Terminal Driver Data Structures 
Filled in/Changed by Can or Will be Used by 
TSC$DATA 
LOS$DATA$SEGMENT System. (1)-(7) 
STATUS (1) System 
INTERRUPT$TYPE (6) System 
INTERRUPTING$UNIT (6) System 
DEV$INFO$ PTR System (1)-(7) 
USER$DATA$PTR System (1)-(7) 
UNIT$DATA 
UNIT$ INFO$ PTR System System 
TERM$FLAGS (0-2) System System 
TERM$FLAGS (3) System (3) 
TERM$FLAGS (4-5) System (3),(6) 
TERM$FLAGS (6-8) System (3),(6),(7) 
IN$RATE System, (3),(6) (3) 
OUT$RATE System (3) 
SCROLL$SNUMBER System System 
BUFFERED$DEVICE$DATA (3) System, (3) 
TERMINAL$DEVICE$ INFORMATION 
NUM$UNITS ICU System 
DRIVER$DATA$SIZE ICU System 
STACK$SIZE ICU System 
TERM$INIT ICU System 
TERM$FINISH IcU System 
‘TERM$SETUP ICU System 
TERM$OUT ICU System 
TERM$ANSWER ICU System 
TERM$HANGUP ICU System 
TERM$CHECK ICU System 
INTERRUPTS 
INTER RUPT$ LEVEL ICU System 
TERM$CHECK ICU System 
DRIVER$ INFO ICU (1)-(7) 
Severe 









CHAPTER 8 
BINDING A DEVICE DRIVER 
TO THE I/O SYSTEM 





You can write the modules for your device driver in either PL/M-86 or the 
ASM86 Macro Assembly Language. However, you must adhere to the following 
guidelines: 


® If you use PL/M-86, you must define your routines as reentrant, 
public procedures, and compile them using the ROM and COMPACT 
controls. 


e If you use assembly language, your routines must follow the 
conditions and conventions used by the PL/M-86 COMPACT size 
control. In particular, your routines must function in the same 
manner as reentrant PL/M-86 procedures with the ROM and COMPACT 
controls set. The ASM86 MACRO ASSEMBLER OPERATING INSTRUCTIONS 
manual describes these conditions and conventions. 


USING THE iRMX™ 86 INTERACTIVE CONFIGURATION UTILITY 


To use the iRMX 86 Interactive Configuration Utility to configure a 
driver that you have written for your application system, you must 
perform the following steps: 


l. For each device driver that you have written, assemble or 
compile the code for the driver. 


Qe Put all the resulting object modules in a single library, such 
as DRIVER.LIB. 


3. Ascertain the device numbers and device-unit numbers to use in 
the DUIBs for your devices. 


a. Use the ICU to configure a system containing all the 
Intel-supplied drivers you require. 


b. Use the G option to generate that system. 


Cc. Use a text editor to examine the file IDEVCF.A86. Among 
other things, this file contains DUIBs for all the 
device-units you defined in your configuration. 


d. Look for the DEFINE DUIB structures in the file. Chapter 2 
lists the format of these structures. Note the device 
number (eighth field) and the device-unit number (tenth 
field) of the last DUIB defined in the file. 


Figure 8-1 lists part of an IDEVCF.86 file which contains 
this information (the file you examine might look 
different, depending on how you configure your system). 
The arrows in the figure point to the relevant fields. 
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e. Use the next available device numbers and device~unit 
numbers in your DUIBs. 


DEFINEDUIB < 
‘lp'; 
OOO001H, 
OF2H, 
00, 

00, 

00, 

00, 
00004H, 
00, 
OOOOBH, 


INITIO, 
FINISHIO, 
QUEUELO, 
CANCELIO, 
DINFOO4, 
00, 
OFFFFH, 
00000H , 
FALSE, 
OO000H, 

0 


MM MOSS OOOH MMM OOS Sm S&S So 


m@ 


&> 
NUMDUIB EQU (THIS BYLE - DUIBTABLE) / SIZE DEFINEDUIB 
BIOSCODE ENDS 


ADEVICE TABLES (NUMDUIB ,0000CH ,005H,003E8H) 
CODE SEGMENT 


ASSUME CS:CGROUP 


Figure 38-1. Example IDEVCF.A86 File 
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4. Create the following: 


ae 


x Use 


The ICU does 


A file containing the DUIBs for all the device-units you 
are adding. Use the DEFINE DUIB structures shown in 
Chapter 2. Place all the structures in the same file. 
Later, the ICU includes this file in the assembly of the 
IDEVCF.A86 file. 


A file containing all the device information tables you are 
adding. Use the RADEV DEV INFO structures shown in Chapter 
2 for any random access drivers you add. Later, the ICU 
includes this file in the assembly of the IDEVCF.A86 file. 


If applicable, any unit information table(s). Use the 
RADEV_UNIT_INFO structures shown in Chapter 2 for any 
random access drivers you add. Add these tables to the 
file created in step b. 


External declarations for any procedures that you write. 
The names of these procedures appear in either the DUIB or 
the Device Information Table associated with this device 
driver. Add these declarations to the file created in step 
b. 


the ICU to configure your final system. When doing so: 


Answer "yes" when asked if you have any device drivers not 
supported by the ICU (this means drivers that you have 
written). 


As input to the "User Devices" screen, enter the pathname 
of your device driver library. This refers to the library 
built in step 2; for example, :Fl:DRIVER.LIB. 


Also, enter the information the ICU needs to include your 
configuration data in the assembly of IDEVCF.A86. ‘The 
information needed includes the following: 


e DUIB source code pathname (the file created in step 
4a). 


e Device and Unit source code pathname (the file created 
in steps 4b through 4d). 


e Number of user defined devices. 
e Number of user defined device-units. 
the rest. 


Figure 8-2 contains an example of the "User Devices" screen. ‘The 
underlined text represents user input to the ICU. In this example, the 
file :Fl:DRIVER.LIB contains the object code for the driver, :Fl:DUIB.SRC 
contains the source code for the DUIBs, and :F1:DEVINF.SRC contains the 
source code for the Device and Unit Information Tables along with the 
necessary external procedure declarations. 
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The code in the DRIVER.LIB file supports one device with two units. 


Refer to the iRMX 86 CONFIGURATION GUIDE for instructions on how to use 
the ICU. 





User Devices 
(OPN) Object Code Path Name [1-45 characters] 


NONE 
(DPN) Duib Source Code Path Name [1--45 characters] 
(DUP) Device and Unit Source Code Path Name [1-45 characters] 


(ND) Number of User Defined Devices [0-OFFH] 0001H 
(NDU) Number of User Defined Device-Units [0-OFFH] 0001H 


Enter Changes [Abbreviations ?/= new_value] : OPN = :F1:DRIVER.LIB 
: DPN = :F1:DUIB.SRC 


: DUP = :F1l:DEVINF.SRC 
: ND = 1 


: NDU = 2 


Figure 8-2. Example User Devices Screen 


USING THE iRMX™ 88 INTERACTIVE CONFIGURATION UTILITY 
To use the iRMX 88 Interactive Configuration Utility to configure a 
driver that you have written for your application system, you must 
perform the following steps in the following order: 

le For each driver, assemble or compile the code. 


Ze When using the ICU: 


a. Answer "208", "215", “common", “random", or "custom" when 
asked for device type. 


b. When prompted, enter the information for the DUIBs, the 
device information tables, and, if applicable, the unit 
information table. 


cc When prompted for linking information, enter the names of 
the appropriate modules. 


The ICU does the rest. 


Hever 
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APPENDIX A 
RANDOM ACCESS DRIVER 
SUPPORT ROUTINES 





This appendix describes, in general terms, the operations of the random 
access device driver support routines. The routines described include: 


INIT$ 10 
FINISH$IO 
QUEUE$IO 
CANCEL$IO 
INTERRUPT$TASK 


NOTE 


For iRMX 88 systems, these names are 
prefixed by "RAD$". 


These routines are supplied with the I/O System and are the device driver 


routines actually called when an application task makes an I/O request to 
support a random access or common device. These routines ultimately call 


the user-written device initialize, device finish, device start, device 
stop, and device interrupt procedures. 


This appendix provides descriptions of these routines to show you the 


steps that an actual device driver follows. You can use this appendix to 
get a better understanding of the I/O System-supplied portion of a device 


driver to make writing the device-dependent portion easier (the random 


access driver support routines follow essentially the same pattern). Or 
you can use it as a guideline for writing custom device drivers. 


INIT$IO PROCEDURE 


The iRMX 86 I/O System calls INIT$1I0 when an application task makes an 


RQ$A$PHYSICAL$ATTACH$DEVICE system call and there are no units of the 
device currently attached. The iRMX 88 I/O System calls INIT$I0 when an 
application task attaches or creates a file on the device and no other 
files on the device are attached. 


INIT$1IO initializes objects used by the remainder of the driver routines, 


creates an interrupt task, and calls a user-supplied procedure to 
initialize the device itself. 
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When the I/O System calls INIT$10, it passes the following parameters: 
e A pointer to the DUIB of the device-unit to initialize 


® In the iRMX 86 environment, a pointer to the location where 
INIT$IO must return a token for a data segment (data storage 
area) that it creates 


e A pointer to the location where INIT$1I0O must return the condition 
code 


The following paragraphs show the general steps that the INIT$IO 


procedure goes through in order to initialize the device. Figure A-l 
illustrates these steps. The numbers in the figure correspond to the 


step numbers in the text. 


INIT$10 







CREATES DATA OBJECT FOR 
DEVICE AND STARTS FILLING IT 







CREATES THE REGION FOR 
ACCESS TO THE QUEUE 


CREATES THE INTERRUPT TASK 





CALLS USER-SUPPLIED PROCEDURE 
TO INITIALIZE CEVICE 












RETURNS TO 1/0 SYSTEM 
PASSING DATA OBJECT AND 
CONDITION CODE 
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Figure A-l. Random Access Device Driver Initialize I/O Procedure 
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It creates a data storage area that will be used by all of the 
procedures in the device driver. The size of this area depends 
in part on the number of units in the device and any special 
Space requirements of the device. INIT$IO then begins 


initializing this area and eventually places the following 
information there: 


e The value of the DS (data segment) register. 


e A token (identifier) for a region (exchange) --- for mutual 
exclusion. 


e An array which will contain the addresses of the DUIBs for 
the device-units attached to this device. INIT$IO places the 
address of the DUIB for the first attaching device unit to 
this array. 


e A token (identifier) for the interrupt task. 


e Other values indicating that the queue is empty and the 
driver is not busy. 


It also reserves space in the data storage area for device data. 


It creates a region. The other procedures of the device driver 
receive control of this region whenever they place a request on 
the queue or remove a request from the queue. INIT$IO places the 
token for this region in the data storage area. 


It creates an interrupt task to handle interrupts generated by 
this device. INIT$IO passes to the interrupt task a token for 
the data storage area. This area is where the interrupt task 
will get information about the device. Also, INIT$IO places a 
token for the interrupt task in the data storage area. 


It calls a user-written device initialization procedure that 
initializes the device itself. It gets the address of this 
procedure by examining the Device Information Table specified in 
the DUIB. Refer to Chapter 3 for information on how to write 
this initialization procedure. 


It returns control to the I/O System, passing a token for the 


data storage area and a condition code which indicates the 
success of the initialize operation. 


FINISH$10 PROCEDURE 


The iRMX 86 I/O System calls FINISH$IO when an application task makes an 
RQ$A$PHYS ICAL$DETACH$DEVICE system call and there are no other units of 
the device currently attached. The iRMX 88 I/O System calls FINISH$IO 


when an application detaches or deletes a file and no other files on the 
device are attached. 
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FINISH$IO deletes the objects used by the other device driver routines, 


deletes the interrupt task, and calls a user-supplied procedure to 
perform final processing on the device itself. 


When the I/O System calls FINISH$I0, it passes the following parameters: 
e A pointer to the DUIB of the device-unit just detached 
e A selector to the data storage area created by INIT$IO 


The following paragraphs show the general steps that the FINISH$IO 


procedure goes through to terminate processing for a device. Figure A-2 
illustrates these steps. The numbers in the figure correspond to the step 


numbers in the text. 


1. It calls a user-written device finish procedure that performs any 
necessary final processing on the device itself. FINISH$IO gets 
the address of this procedure by examining the Device Information 
fable specified in the DUIB. Refer to the Chapter 4 for 
information about device information tables. 





FINISHSO 






CALLS USER-SUPPLIED 
PROCEDURE TC FINISH UP 
PROCESSING ON THE DEVICE 







DELETES INTERRUPT TASK FOR 
DEVICE AND RESETS INTERRUPT 






DELETES REGION AND DATA OBJECTS 
USED BY THIS DEVICE DRIVER 





©) 


RETURNS TO THE !/O SYSTEM 


1876 


Figure A-2. Random Access Device Driver Finish I/O Procedure 
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2. It deletes the interrupt task originally created for the device 
by the INIT$IO procedure and cancels the assignment of the 
interrupt handler to the specified interrupt level. 


3. It deletes the region and the data storage area originally 
created by the INIT$I0O procedure, allowing the operating system 
to reallocate the memory used by these objects. 


4, It returns control to the I/O System. 


QUEUE$IO PROCEDURE 


The I/O System calls the QUEUE$L10 procedure to place an I/O request on a 


queue of requests. This queue has the structure of the doubly-lLinked 
list shown in Figure 2-2. If the device itself is not busy, QUEUE$IO 
also starts the request. 


When the I/O System calls QUEUE$L0O, it passes the following parameters 
e A token (identifier) for the IORS 
e A pointer to the DUIB 


e A token (identifier) for the data storage area originally created 
by INIT$IO 


The following paragraphs show the general steps that the QUEUE$I0 


procedure goes through to place a request on the I/O queue. Figure A-3 
illustrates these steps. The numbers in the figure correspond to the 
step numbers in the text. 


1. It sets the DONE field in the IORS to OH, indicating that the 


request has not yet been completely processed. Other procedures 
that start the I/O transfers and handle interrupt processing also 


examine and set this field. 


2. It receives control of the region and thus access to the queue. 
This allows QUEUE$IO to adjust the queue without concern that 
other tasks might also be doing this at the same time. 


3. It places the LORS on the queue. 


4, It calls an I/O System-supplied procedure to start the processing 
of the request at the head of the queue. This results in a call 
to a user-written device start procedure which actually sends the 
data to the device itself. This start procedure is described in 
Chapter 5. If the device is already busy processing some other 
request, this step does not start the data transfer. 


5. It surrenders control of the region, thus allowing other routines 
to have access to the queue. 
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CANCEL$IO PROCEDURE 


The I/O System calls CANCEL$IO to remove one or more requests from the 
queue and possibly to stop the processing of a request, if it has already 
been started. The iRMX 86 I/O System calls this procedure in one of two 
instances: 


e If an iRMX 86 user makes an RQ$A¢PHYSICAL$DETACH$DEVICE system 
call and specifies the hard detach option (refer to the iRMX 86 
BASIC I/O SYSTEM REFERENCE MANUAI, for information about this 
system call). The hard detach removes all requests from the 
queue. 
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Figure A-3. Random Access Device Driver Queue I/O Procedure 
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e If the job containing the task that makes an I/O request is 
deleted. In this case, the I/O System calls CANCEL$IO to remove 
all of that task's requests from the queue. 


When the I/O System calls CANCEL$I0O, it passes the following parameters: 
e An ID value that identifies requests to be cancelled 
e A pointer to the DUIB 
e A token (identifier) for the device data storage area 


The following paragraphs show the general steps that the CANCEL$IO 
procedure goes through to cancel an I/O request. Figure A-4 illustrates 
these steps. The numbers in the figure correspond to the step numbers in 
the text. 


l. It receives access to the queue by gaining control of the 
region. This allows it to remove requests from the queue without 
concern that other tasks might also be processing the IORS at the 
same time. 


2. It locates a request that is to be cancelled by looking at the 
cancel$id field of the queued IORSs, starting at the front of the 
queue. 


3. If the request that is to be cancelled is at the head of the 
queue, that is, the device is processing the request, CANCEL$I0 
calls a user-written device stop procedure that stops the device 
from further processing. Refer to the Chapter 5 for information 
on how to write this device stop procedure. 


4, If the request is finished, or if the IORS is not at the head of 
the queue, CANCEL$I0O removes the IORS from the queue and sends it 
to the response mailbox (exchange) indicated in the IORS. 


5. It surrenders control of the region, thus allowing other 
procedures to gain access to the queue. 
NOTE 
The additional CLOSE request supplied 
by the I/O System will not be processed 


until all other requests with the given 
cancel$id value have been dealt with. 
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Figure A-~4. Random Access Device Driver Cancel I/O Procedure 
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INTERRUPT TASK (INTERRUPT$TASK) 


As a part of its processing, the INIT$IO procedure creates an interrupt 
task for the entire device. This interrupt task responds to all 
interrupts generated by the units of the device, processes those 
interrupts, and starts the device working on the next I/O request on the 
queue. 


The following paragraphs show the general steps that the interrupt task 


for the random access device driver goes through to process a device 
interrupt. Figure A-5 illustrates these steps. The numbers in Figure 
A-5 correspond to the step numbers in the text. 


l. It uses the contents of the processor's DS register to obtain a 
token (identifier) for the device data storage area. This is 
possible because of the following two reasons: 


@ When INIT$IO created the interrupt task, instead of 


specifying the correct contents of the DS register, it passed 
the token of the data storage area as the contents of the 
task's DS register. 


® When the INIL$IO procedure created the data storage area, it 


included the correct contents of the DS register in one of 
the fields. 


When the interrupt task starts running, it saves the contents of 
the DS register (to use as the address of the data storage area) 
and sets the DS register to the value listed in the field of the 
data storage area. Thus the task has the correct value in its DS 
register, and it has the address of the data storage area. This 
is the mechanism that is used to pass the address of the device's 
data storage area from the INIT$IO procedure to the interrupt 
task. 


2. For iRMX 86 systems, it makes an RQ$SET$INTERRUPT system call to 
indicate that it is an interrupt task associated with the 
interrupt handler supplied with the random access device driver. 
It also indicates the interrupt level to which it will respond. 


For iRMX 88 systems, it makes an RQ$ELVL system call to enable 
the nucleus-provided default interrupt handler. 


3. It begins an infinite loop by waiting for an interrupt of the 
specified level. 


4, Via a region, it gains access to the request queue. This allows 
it to examine the first entry in the request queue without 
concern that other tasks are modifying it at the same time. 


5. It calis a user-written device-interrupt procedure to process the 


actual interrupt. This can involve verifying that the interrupt 
was legitimate or any other operation that the device requires. 
This interrupt procedure is described further in Chapter 3. 
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Figure A-5. Random Access Device Driver Interrupt Task 
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If the request has been completely processed, (one request can 
require multiple reads or writes, for example), the interrupt 
task removes the IORS from the queue and sends it as a message to 
the response mailbox (exchange) indicated in the IORS. If the 
request is not completely processed, the interrupt task leaves 
the IORS at the head of the queue. 


If there are requests on the queue, the interrupt task initiates 
the processing of the next I/O request by calling the 
user-written device-start procedure. 


In any case, the interrupt task then surrenders access to the 


queue, allowing other routines to modify the queue, and loops 
back to wait for another interrupt. 


weve 
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APPENDIX B 
EXAMPLES OF 
DEVICE DRIVERS 





This appendix contains four examples of device drivers. The first 
example is a common driver which drives a line printer. The second is a 
random access driver, which drives a iSBC 206 disk controller. The third 
example is an 8274 terminal driver. (The contents of the INCLUDE files 
that these drivers use are listed in the last section of this appendix.) 


Note that the names of the procedures in the examples are not 
deviceSstart, deviceSinterrupt, etce, as in the text of this manual. 
This is because the actual names are placed in the appropriate DUIBs 
during configuration. 


Table B-l lists the device driver example file names and the pages on 
which they appear. 


Table B-l. Device Driver Examples 












Description 









iprntr. p86 Driver for a line printer 


1206ds. p86 Driver for an iSBC 206 disk controller 







x8274. p86 8274 terminal driver 


INCLUDE files for above device drivers 
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PL/M-86 COMPILER  xprntr. pad 


iRMX 86 PL/M-86 V2.3 COMPILATION QF MODULE XPRNTR 
QBJECT MODULE PLACED IN :F 1: XPRNTR. OBJ 
COMPILER INVOKED BY: :LANG:pla@6 :F1:XPRNTR.PBG COMPACT OPTIMIZE(3) ROM PAGEWIDTH(132) NOTYPE 


oes {‘xprntr,pa4") 
* xprntr.pBd 


+ 
+ This module iapleaents centronix-type interface line ee 
# driver. It is written as a ‘comaon’ device driver. It is 
t assumed that the reader is familiar with the 8255 chip. 
* 
% 
# LANGUAGE DEPENDENCIES: 
. COMPACT ROM OPTIMIZE‘3) 
¥! 
it 
¥ INTEL CORPORATION PROPRIETARY INFORMATION 
# 
$ This software is supplied under the teras of a 
* license agreement or nandisclosure agreement with 
+ Intel Corporation and may not be copied or disclosed 
# except in accordance with the teras cf that agreeaent. 
¥ 
+/ 
i yprntrs DQ; 


$include(:¢l:xcoman. lit) 
= $save nolist 
$include(:fl:xparam. lit) 
= save nolist 
$include(:flsxnutyp. lit) 
=  $save nolist 
$include(:fisxiors. lit) 
= $cave nolist 
finclude(:¢iixduib. lit) 
= save nolist 
finclude(:fisxprntr. lit) 
= $save nolist 
finclude(:#1:¥9255, Lit) 
=  $save nolist 
finclude(:flixorerr. lit) 
= $save nolist 
finclude/:f0:nsleep.ext) 
= lle NOLIST 
‘+ 


, literal declaration 
t 
23. (ot DECLARE 


TABSCHAR LITERALLY ‘09H’, 
SPACE LITERALLY ‘20H’; 


fsubtitle(‘printer$start$interrupt ') 


it 
printer$start/printerSinterrupt 
start/interrupt procedure for the line printer 


CALLING SEQUENCE: 


t 
¥ 
# 
* 
# CALL printer$start#interrupt (iors$p, duib$p, ddatagp); 
# 
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* INTERFACE VARIABLES: 
t iorssp - 1/0 request/result segaent pointer 
* duib$p - painter to the device-unit info. block 
t ddata$p - pointer to the device(printer) data segment. 
& 
* CALLS: None 
+ 
#/ 
printer$start$interrupt: PROCEDURE (iors$p, mt ddatasp) 
PUBLIC REENTRANT; 
DECLARE 
(iors$p, duib$p, ddata$p) POINTER; 
DECLARE 


iors BASED iors$p IQSREQSRESSSEG 
duib BASED duibgp DEVSUNIT$INFOSBLOCK; 


R 
dinfotp POINTER 
dinfo BASED dinfosp PRINTERSDEVICESINFO; 
DECLARE 
ee POINTER, 
(char BASED butfer$p)(1) BYTE; 


dinfosp = duib.devicefinfosp; 


[* 
* test for spurious interrupts 


* 
IF iors$p = 0 THEN 
00; 


’ 
it 


oe off the interrupt and return 

# 
OUTPUT (dinfo.Control$port) = INTSDISABLE; 
RETURN: 

END; 

DO CASE (iors, funct); 


i¥ read #/ 


"iors. status = ESIDOR; 
iors.done = TRUE; 


END; 
/* write #/ 


0; 
ar as the buffer gointer #/ 
bufterg$p = iors.butfép; 


/* disable printer interrupt #/ 
OUTPUT {dinfo.Contral$part) = INT$DISABLE; 


DQ WHILE (iors.actual ¢ iors.count); 


it 

* test for printer fa and not paper cut. if not ready 
* or paper out then wait forever. 
¥ 


DO WHILE (((INPUT(dinfo.CSport) AND PRINTERSREADY) = 0) OR 
({INPUT(dinfo.C$part) AND PAPERSQUT) <> 01); 
/* sleep for £00 nucleus clock intervals #/ 
eae rafsleep(100, iors. status); 


‘ 
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It 


* convert TAB character to a SPACE character if the 
\ printer does not handle thea 


k 
IF ({char (iors.actual) = TABSCHAR) AND 


{{dinto.tab$contral) = FALSE)) 


THEN char(iors.actual) = SPACE; 


t 
# 1's complement the character and send it to the 
* printer. Paort-A is the data port 


#/ 
eae ener, = NOT(char (iors.actual)); 
¥ 


# strobe the line printer 
# this is a way of telling the printer that there is 
* valid data on the bus 


¥/ 


QUTPUT(dinfo.Control$port) = STROBESON: 


QUTPUT (dinfo.Contral sport) 
t 


STROBESOFF; 


- increment the count of chars printed 
# 


iors.actual = 
/t 


iors.actual + 1; 


* test whether printer acknowledgement bit is set 


t 
IF a eee: AND CHARSACK AND CHARSACKSCOMPLETE) = 0 


DO; 
/* 


+ printer didn t acknowledge. popenty it has 


* started printin 
. and return(prin 


t 


. 50 enable the printer interrupt 
er will interrupt when it’s done) 


t 
QUTPUT{dinfo.Control$port) = INTSENABLE: 


RETURN; 


END; 
END; /* end of BO WHILE statement #/ 


it 


# set iors.done to TRUE 
* set iors.status to OK 


*/ 
iors, status = ESOK; 


iors.done = TRUE 
END; 


‘* seek #/ 


"rors.status = ESIDDR: 


iors.done = TRUE 


/# special #/ 
DQ; 


"jors.status = ESIDDR; 
iors.done = TRUE; 


END; 


/# attach device #/ 


aT initialize the 8255 #/ 


i 


4 
$ 


QUTPUT(dinfo.Control$port) = MODESWORD; 


iors.status = E#OK 


iors.done = TRUE 
D; 


or 
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ie detach device #/ 


733 
74 «4 "iors. status = ES$OK; 
774 iors.done = TRUE; 
78 4 ND; 

/* apen #/ 
79,3 DQ; 
8g = 4 iors.status = E$OK; 
gi 4 iors.dane = TRUE; 
92 4 END: 

/* clase #/ 
on : 
84 4 iors.status = ESQK; 
a 4 iors.done = TRUE; 
$4 4 END; 
a7 3 END; /# end of 20 CASE statement 4/ 


8 2 END printer$startSinterrupt; 


Pa amr oa Se Oe nM Oe oa 


printer$stop 
stop procedure for the line printer 


CALLING SEQUENCE: 
CALL printer$stop (iors#p, duibfp, ddata$p); 


INTERFACE VARIABLES: 
iors$p - 1/0 request/result segment pointer 
duibfp - pointer ta the device-unit info, Slack 
ddata$p - pointer to the device(printer) data segment. 


CALLS: None 


/ 


ef { Eee PROCEDURE ‘iors$p, duiidn, ddata#p) PUBLIC REENTRANT: 
j A 

(iors$p, duib$p, ddatafp) POINTER; 
1 DECLARE | 

iors BASED iors$p IOSREQSRESSSEG 

duib BASED duib$p DEVSUNITSINFOSBLOCK; 
W 2 DECLARE 

dinfo$p POINTER, 

dinfo BASED dinfosp PRINTERSDEVICESINEO; 


ra 


ro 


* turn off the printer interrupt 
# set iors.done to TRUE 
* set iors,status to EfOK 


t/ 
Moe dinfo$p = duib.devicedinfosp; 
94 2 QUTPUT (dinfa.Control$part) = INTSDISABLE; 
9 2 tors.status = ESOK; 
96 2 iors.done = TRUE; 


2 END printer#stop; 
99 END xprntr; 
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PL/M-85 COMPILER ari 
Module Header 


iRMX 86 PL/M-86 V2.3 COMPILATION OF MODULE X2060S 
OBJECT MODULE PLACED IN sFi:X206D5.0BJ 
COMPILER INVOKED BY: sLANG:plm86 :F1:X206D5.P84 COMPACT OPTIMIZE(3) ROM PAGEWIDTH{132) NOTYFE 


$title(’x206ds.086') 
fsubtitlet Module Header ') 


/t 
* x206ds.p84 


é 

# iSBC 206 device 

t 

gues DEPENDENCIES: COMPACT ROM OPTIMIZE(3) 
t 


{ ¥20dds: DO; 
[t 
t INTEL CORPORATION PROPRIETARY INFORMATION 
+ 
t This software is supplied under the terms of a 
# license agreement or nondisclosure agreement with 
t Intel Cornoration and may not be copied or disclosed 
+ except in accordance with the teras af that agreeaent. 
t 
#/ 


$include(s¢tixcomon. lit) 
= save nolist 
Finclude(:fisxnutyp. lit} 
= #save nolist 
Finclude(:¢lsxparaa.iit) 
= $cave naolist 
$include(:fisxictyp. lit) 
= save nolist 
Sinclude(s¢lixiors. lit} 
= $5ave nolist 
Fincluce(:ffixduib. lit) 
=  $save nolist 
$includei:¢isxdrinf. lit) 
= $save nolist 
$include(:¢isx20éin. lit) 
= save nolist 
Fincludets#lix20ddv. lit: 
= save nolist 
$include(:firvexcep. lit) 
= save nolist 
finclude(:fi:zioexc. lit) 
= save nolist 
$include(sf¢lixradsf. lit) 
=  $save nolist 


$includetsflix20ddp.ext) 
= save nolist 

Sinclude(sflix206dc. ext) 
= save nolist 

Sinclude(sfisx204fa.ext} 
= $save nolist 

Finclude(:flixnotif.ext} 
= save nolist 
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$subtitle(‘Local Data’) 


[* 
t 


needfreset array used to determine if device needs to be 
a reset after an error. Indexed by status. 
# 


DECLARE 


it 
# 
t 


need$reset (24) 


SE, 


E 
FALSE, 
FALSE, 
TRUE 
FALSE, 
FALSE. 


unitfstatus is used to set unit 


Indexed by status, 


DECLARE 


{t 
¥ 
t 
¥/ 


uni tfstatus (24) 
TOSUNCLASS, 
TOSSOFT, 
1OSS0FT, 
TOSHARD, 
1OSSOFT 
TOSUNCLASS, 
TOSUNCLASS, 
TOSUNCLASS, 
TOSHARD 
IOSUNCLASS , 
1OSS0FT, 
ICSSOFT. 
TOSHARD 
TOSUNCLASS, 


1OSWRPROT 
LOSUNCLASS 
10$S0FT 
IOSUNCLASS, 
TOSUNCLASS, 
IOSUNCLASS, 
TOSOPRINT) : 


drivedready 1s used to find the 


in the drive status, 


BYTE DATA( 


BYTE BATAC 
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/* Successful completion +#/ 

‘* I) field miscompare #/ 

/* Data field CRC error #/ 

/* special for incorrect result$type +#/ 
/* Seek error #/ 


/* Tllegal Record Address #/ 


/*# ID Field CRO error #/ 
/* Protacol error #/ 
/* Ullegal Cylinder Address #/ 


/* Record not found #/ 
/* Data Mark Missing #/ 
/* Format Error #/ 

/* Write Protected #/ 


/*# Write Error #/ 


/* Drive Not Ready #/ 


status field in iors. 


/# Successful completion #/ 

/* 1D field miscompare ¥#/ 

/* Data field CRC error #/ 

/‘* special for incorrect result$type #/ 
/# Seek errar #/ 


ngs 


/* Tilega!l Record Address #/ 


/# ID Field CHC error #/ 
/* Protocal error #/ 
‘* T}legal Cylinder Address #/ 


- 


/# Record not found #/ 
/* Data Mark Missing #/ 
/* Format Error #/ 

{* rite Protected #/ 


/* rite Error #/ 


/* Drive Not Ready #/ 


drive ready bit 
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439° DECLARE 
drivesready(4) BYTE DATA‘O20H,040H, OL0H,020H); 


$subtitle( i206sstart') 


it 
# i206$start : 
' start procedure for the iSHC 206 
# CALLING SEQUENCE: 
t CALL i20$start{iors$p, duibfp, ddatagp); 
t 
* INTERFACE VARIABLES: 
# tors$p - 1/0 Request/Result de ade pointer 
* duib§p - pointer to Device-Unit Information Black 
* ddatagp - device data seqment pointer. 
t 
* CALLS: 
# 10$206 
+ format$204 
* send#204$iopb 
* 
$/ 
49 i206$start: PROCEDURE (iors#p, duibfp, ddatago) PUBLIC REENTRANT: 
w0 2 DECLARE 
iors$p POINTER, 
duib$p POINTER, 
ddata$p POINTER: 
si 2 DECLARE 
iors BASED tors$p [G$REQSRESESEG 
duit BASED duibfp DEVSUNITSINFOSBLOCK, 
dinfosp POINTER, 
dinfo BASED dinto$p I204$DEVICESINFO, 
uinfosp POINTER, 
uinfa BASED uintosp LSIOSUNTTSINEG, 
ddata BASED ddatatp IGSPARM$BLOCK$204, 
hase WORD, 
dummy BYTE: 
a2: <2 dinfofp = duib.devicesinfagp; 
os 4 base = dinfo, base: 
v4 2 uinfo$p = duibsunittintosp; 
5-2 IF {ddata.restore) THEN 
g4 2 RETURN; 
ae be dofcaseffunct: 
DO CASE iors. funct; 
/t 
# in the following calls the @ddata is literally 
* 1opbfp (i,e., the pointer to the iopb). 
} 
a) cera 
594 " CALL in$206(base, iors$p, duibsp, @ddata): 
4) 4 END case$read; 
to caseferite: 
2 4 " CALL io$206(base, iors$p, duibfp, Sddata): 
63 4 END casefwrite; 
64 3 casesseek: 
65 4 " CALL io$206(base, iorstp, duib$p, @ddatal: 
66 4 END case$seek; 
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casesspecsfunct: 
DQ; 


IF iors. subsfunct = FSSFORMATSTRACK THEN 
ae format$20d(base, iorstp, duib$p, @ddata); 


DQ; 


iors.status = a 
iors,actual = 
iors.done = rau 


END: 
END casefspecsfunct; 
kaa 


» duaay = (duib. aa = 912); 
(input { rine ea$port) OR O73H) <> OFBH) OR 
Ny eeaeae $canfigtpart) AND SHL{Q1OH,SHRiduib.unit,2))) ¢? 0) <> dummy) THEN 
i] 

iors.status = E$103 
iors.unit$status = IOSOPRINT; 
iors.actual = 9 
iors,done = TRUE; 


ETURN: 
END: 
ddata. inter = eee 
ddata.instr = oreso 


Op; 
IF a seieso0u san iveck: @ddata) THEN 


* the board would not accept the iopb 

t SOses 

#/ 

DO; 

iors, status = E$]0; 
iors.,unit#status = IQS50FT OR SHLfinput{result$bytegport), 9); 
iors,actual = 03 
iors,done = TRUE; 


END caseSattachtdevice; 
casesdetachSdevices 
%, iors.status = ESOK; 
tors.done = TRUE; 
END case$detach#devices 
casefopen: 
DO; 
iors.status = ESOK; 
iors.done = TRUE; 
END casefopen; 
casetclose: 
’ jors.status = E$0K; 
iors.done = TRUE; 
END casefclose; 
END do$cases$funct; 


END i204$start; 
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$subtitle('1206$interrupt’) 


~— 


Ce ee ee 


1Z06$interrupt 
interrupt procedure for the iS8C 204 


CALLING SEQUENCE: 
CALL 1206$interrupt(iors$p, duibfp, ddatasp); 


INTERFACE VARIABLES: 
iors$p - 1/0 Request/Result segment pointer 
duib$p - pointer to Device-Unit Information Block 
ddatasp - device data segaent pointer. 


CALLS: 
i206$start 
send$206$iapb 
rgfsend$message 


/ 
1206Sinterrupt: PROCEDURE {iorssp, duibfo, ddata$p) PUBLIC REENTRANT; 
DECLARE 


rorsdp POINTER, 
duib$p POINTER, 
ddatasp POINTER: 

DECLARE 
lors EASED iorstp IO$REOSRES$SEG 
duib BASED duibso DEVSUNITSINFOSBLOCK, 
dinfo$p POINTER, 
dinfo BASED dintos$p I204$DEVICESINEO 
ddata BASED ddatasn [OSPARNSELOCK$206, 
tomp BYTE, 
fase WORD, 


spindle WORD, 
status WORD; 


dinfo$p = duib.devicetintosp; 
base = dinfo.base; 
spindle = shr(duibvunit,.2)3 ‘* 4 units/soindle #/ 


IF (input(result$typefcort) AND 3) = 9 THEN 
donedints 
DO; 


status = inputiresultsbytesport); 


IF ddata.restore THEN 
didgrestore: 
0; 
ddata.restore = FALSE: 
ddata.statusispindle) = status; 
TF iors$p «> 9 THEN 
restart: 


CALL i20b#start‘iors#p, ddata$p, duibsp); 
END restart; 
RETURN: 
END did$restore; 


ddata.Status(spindle) = status; 


IF iors$p ¢} & THEN 
validsiors: 


"TF status ¢> 0 THEN 
had$status: 


‘ 
ua 
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iors.status = ESI: 
IF (status <= O10H) THEN 
teap = status; 
ELSE 
temp = shr(status, 4) + QOFH; 
iors,unit$status = unit#status( tenp) OR SHL{status,8); 
iors.actual = 03 
iors.done = TRUE: 
IF needgreset ( ddata, status (iors.unit / 4)) THEN 
recalibrate: 


} 
/* 
* Note: aust index drive select 
i from iors.unit. 
* 
ddata.inter = inter$on$mask; 
ddata.instr = restorescp; 
ddata, restore = send#206$iopb (dinto. base, @ddata); 
END recalibrate; 


END bad$status; 
a is 


bf 
lors.actual = 1ors.counts 
iors.done = TRUE; 
END ok$status: 
END valid$iors; 
END done$int; 
eee erent 
} 
teap = input (inter fstat$port) ; 
DO spindle=0 TO 3; 
IF cath AND SHL (1, Spindle!) «> 9 THEN 
GOTU found$spindle; 
END; 


found$spindle: 
ape = SHL (spindle, 2} 
DO teap=spindle TG enema 43s 
IF ({inputtresultSbyte$oort) AND drivetready(spindle)) = 0) THEN 
CALL notifyitemp, @ddata); 


END: 
END statussints 


END i206$interrupt; 
$subtitlel'i20ssinit’) 


i¥ 
# i206finit 
* init procedure for the i5BC 204 
é 
* CALLING SEQUENCE: 
* CALL i20d$init(duib$p, ddata$p, status$p); 
t 
* INTERFACE VARIABLES: 
t duib#p - pointer to Device-Unit para Black 
* ddatatp - device data eeneel painter, 
* status$p - pointer to WORD indicating status of operation 
t 
* CALLS: 
t ‘nane?> 
e 
*/ 


i206finit: PROCEDURE (duib$p, ddatagp, status#p) PUBLIC REENTRANT; 
DECLARE 


duib$p POINTER, 
ddatatp POINTER, 
statusfp POINTER: 
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EXAMPLES OF DEVICE DRIVERS 


169 2 DECLARE 
duib BASED duib$p DEVSUNITSINFOSBLOCK, 
dinfotp POINTER, 
dinfo BASED dinfo$p I204$DEVICESINFO 
ddata BASED ddatasp LOSPARMSBLOCK$204, 
status BASED status$p WORD; 
179 2 DECLARE 
i WORD; 
{7l 2 dinfo$p = duib.devicesinfagp; 
i 
oe 206; not there or not hard disk ==> Qops! 
# 
bi2 2 sf Tae Nl = 0s 
1732 status = ESOKs 
174 2 ddata.restore = FALSE; 
17302 END i204finit; 


176 1 END x204ds; 


MODULE INFORMATION: 


CODE AREA SIZE O300H 78D 


CONSTANT AREA SIZE : O034H a2 
YVARTABLE AREA SIZE = 000H )D 
MAXIMUM STACK SIZE = 2046H 79D 


1037 LINES READ 
) PROGRAM WARNINGS 
® PROGRAM ERRORS 


DICTIONARY SUMMARY: 
FakE MEMORY AVAILABLE 
{8KH MEMGRY USED = (18%) 
OKA DISK SPACE USED 

END JF PL/N-96 COMPILATION 


fL/M-84 COMPILER w206ic.086: 1SBC 206 1/0 Nodule 
Madule Header 


LAMX 84 PL/M-96 V2.3 COMPILATION OF MODULE X20610 
OBJECT MODULE PLACED IN :F1:X20679, OBJ 
COMPILER INVOKED BY: :LANGipla@é :F1:X20610.P86 (COMPACT OPTIMIZE(3) ROM PAGENIDTH(132) NOTYPE 


eC i98C 204 [/0 Module’) 


$subtitlet Module Header ‘) 
i x2Gdio: DQ; 

it 

* INTEL CORPORATION PROPRIETARY INFORMATION 

* 

* This software is supplied under the terms of a 

t license agreement ar nondisclosure agreement with 

* Intel Corporation and may rot be copied or discicsed 
* except in accordance with the terms cf that agreeaent. 
+ 

$/ 
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EXAMPLES OF DEVICE DRIVERS 


/k 
* This module modifies the 206 parameter block and passes the 
# address of it ta the iSBC 204. 


* 
ee DEPENDENCIES: COMPACT ROM OPTIMIZE(3) 
t 


Sinclude(:f{lsxcomon. lit) 
$save nalist 
Sinclude(s¢{sxnutyp. lit) 
$save nolist 
Finclude(sfisxiotyp. lit) 
$save nolist 
$include(sflsxparan. lit) 
$save nalist 
$include(:flsx20édy.1it) 
$save nolist 
Sincludets¢lsx20din, Lit) 
fsave nalist 
Sincludet:flixiors. lit) 
$save nolist 
$include(:flixduib. lit) 
fsave nolist 
Sinclude(sflixtrsec. lit) 
$save nolist 
Finclude(:fisxexcep. lit) 
$save nolist 
$include(:flixioexc. lit) 
$save nolist 
$includei:fl:x20ddc. ext) 
$cave nolist 


i* 
* this module also does seeks 
a/ 


DECLARE 
:20etoptcades (*) BYTE DATA 
READSOP 
WRITESOP, 
SEEK SOP 


\s 
ry 


$subtitle(io$206: iSBC 206 1/0 Module} 


} 
i 


E: 

# 10$204 

t 1/0 module (read/write/seek) 

+ 

* CALLING SEQUENCE: 

+ CALL i0$206 (base, iors$p, duibsp, iopb$p!);. 

t 

* INTERFACE VARIABLES: 

* base - base address of the board. 

* iors#p ~ 1/0 Request/Result ce gt pointer 
t duib$p - pointer to Device-Unit Information Block 
* lopb$p ~ pointer to I/O parameter hlock. 

+ 

& CALLS: 

7 send$204$iopb (base, @icpb) 

$ 


i0%206; PROCEDURE (base, iors$p, duib$p, topb$p} REENTRANT PUBLIC; 
DECLARE 
base WORD 
iors$p POINTER, 
duib$p POINTER, 
Lopb$o POINTER: 
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EXAMPLES OF DEVICE DRIVERS 


33.02 DECLARE 
iors BASED iorsfp IOSREQS$RES$SEG, 
ts DWORD, 
ts$o TRACKSSECTORSSTRUCT AT(@ts) 
duib BASED duib$p DEVSUNITSINFOSBLOCK, 
iopb BASED icph$p [OSPARM$BLOCK$204, 
platter BYTE, 
Spindle BYTE, 
surface BYTE: 
342 ts = iors, dev$loc; 
a ce Spee = shr{iors.unit, 2); /# 4 units/spindle #/ 
382 platter = iors.unit AND 02H; /* (as above ) #/ 
i ee surface = tsfo.track AND OCOOLH: /# select surface #/ 
4) 2 iopb,inter = INTERSONSNASE; 
4{ 2 1opb.cylfadd = shr(tsfc.track, 1); /* track/2 = cylinder #/ 
422 loph.instr = i206$op$codestiors, funct) QR 
HE ei &) OR 
shi(platter, &) OR 
shlisurface, ob; 
It 
# note: the controller only supports S12 or 129 byte sectors 
¥ 50 na checking 15 done. 
¥ 
ts 2 topb.rfcount = iors.count / duib.dev$gran; /* divide by sectors size #/ 
if 2 iopb.recfadd = {ts$a.sector + 1) OR 
shr(tsfo.track AND O200H, 2); /# (cyl AND OL00H) / 2 #/ 
ai 2 iopb.buff$p = tors. buff$p; 
44 2 IF NOT send$204$iopbibase, @iopb) THEN 
{t 
* the board did not accept the iopb so... 
£/ 
472 D0; 
49 3 lors.status = [QSS{)FT; 
49° 3 iors.actual = 9; 
2) 3 iors.done = TRUE; 
ae END; 
a2 2 END 1o#206: 
So. vf END x204i03 


MODULE INFORMATIONS 


CODE AREA SIZE 
CONSTANT AREA S 
VARTABLE AREA 5 
MAXIMUM STACK & 
S05 LINES READ 


— os 


QODSH 213 


£2 003H 3D 
F=0000H 09 
E=0022H 34D 


0 PROGRAM WARNINGS 


) PROGRAM ERRORS 


DICTIONARY SUMMARY: 


FokB MEMORY AVAILABLE 


[2KB MEMORY USED 


(127) 


OKB DISK SPACE USED 
END OF PL/M-84 COMPILATION 
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EXAMPLES OF DEVICE DRIVERS 


x206dc: iSBC 206 parameter handler 
Madule Header 


iRMX 84 PL/M-B6 V2.3 COMPILATION OF MODULE X2060C 


OBJECT MODULE PLACED 
COMPILER INVOKED BY: 


IN Fi: X206DC,OBd 
:LANG:pim86 :F1sX206DC.P86 COMPACT OPTIMIZE(3) ROM PAGEWIDTH(132) NOTYPE 


ftitle(’x20hdc: iSBC 206 parameter handler‘) 
$subtitle( Module Header ') 


{ y20dde: DOs 
/* 
f INTEL CORPORATION PROPRIETARY INFORMATION 
t 
+ This software is supplied under the terms of a 
+ license agreement or nondisclasure agreement with 
$ Intel Corporation and may not be copied or disclosed 
+ except in accordance with the teras of that ‘agreement. 
t 
#/ 
/* 


* This module contains the commands for the 204 contrcller. 


$ 
# LANGUAGE DEPENDENCIES: COMPACT ROM OPTIMEZE(3) 
¥} 


Sinclude(:fl:xcomon, lit) 
=  $save nolist 

Finclude(sfisxnutyp. lit) 
= save nolist 

$include(sfisx2dédv, lit) 
= save nalist 


$subtitle(‘Send 206 1/0 Parameter Block‘) 


i* 
* eee ate 
t send the iSBC 204 the address of the parameter block 
¥ 
* CALLING SEQUENCE: 
+ CALL send$206f1aph (base, iopbfp); 
7 
# INTERFACE VARIABLES: 
t base - base address of board. 
# lopb$p - 1/0 parameter block pointer 
¥ 
# CALLS: 
+ “none? 
#/ 
4 sends204$ionb: PROCEDURE ‘base, iopbfp) BOOLEAN REENTRANT PUBLIC; 
D0” *2 DECLARE 
base WORD 
jopb fp POINTER: 
li 2 DECLAR 
iopb$p$o  FSOVERLAY ene ; 
iopb BASED iopb$p [0% ARMSBLOCK$206, 
drive BYTE; 
lg: drive = shrfiopb.instr AND Q30H, 4); 
1, 2 drive = shl(O1H,drive); 
2 IF (inpué (contrailersstat) | = (CGMMANDSSUSY OR drive) THEN 
ig, <2 RETURN (FALSE) ; 
14 2 output (lo$otf$port) = low (iopb$pto.affset); 
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EXAMPLES OF DEVICE DRIVERS 


1? <2 IF Oe conte eyeneae! AND COMMAND$BUSY) <> 0 THEN 
19 2 RETURN (FALSE) s 
i* 
ee it to here sa output rest of topb address 
t 
1e<2 cutput (lo$seg$port) = low (iopb$p$o. base); 
a0 2 output at Maa = high (iapb pa. basel 
1 output (hi$of#$port) = high (iopb$p$o.offset) 
ee 2 RETURN(TRUE) ; 
23. 2 END send$206$iopb; 


2 END x204dc3 


MODULE INFORMATION: 


CODE AREA SIZE = 0080H 96D 
CONSTANT AREA SIZE = 0000H OD 
VARIABLE AREA SIZE = G0QQH 0D 


MAXIMUM STACK SIZE = O0OCH 129 
208 LINES READ 

Q PROGRAM WARNINGS 

Q PROGRAM ERRORS 


DICTIONARY SUMMARY: 
QokB MEMORY AVAILABLE 
SKB MEMORY USED (5%) 
GKB DISK SPACE USED 


END OF PL/M-86 COMPILATION 


PL/M-B846 COMPILER ¥206¢8.086 
Module Header 


iRMX 86 PL/M-86 V2.3 COMPILATION OF MODULE X206FM 
OBJECT MODULE PLACED IN :F i: X206FN. OBJ 
COMPILER INVOKED BY: sLANGsplm@6 :Fi:X206FM.P86 COMPACT GPTIMIZE(3) ROM PAGEWIDTH{132) NOTYPE 


to. 
$subtitle( ‘Module Header ') 


it 
* ¥206f9.p86 


iSBC 206 device 
formats one track on hard disk 


pes DEPENDENCIES: COMPACT ROM OPTIMIZE(3) 


1 x20b¢m: DO; 


wR sR AR OS kK OK 
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EXAMPLES OF DEVICE DRIVERS 


it 

# INTEL CORPORATION PROPRIETARY INFORMATION 

¥ 

+ This software is supplied under the terms of a 

+ license agreement or nondisclosure agreesent with 

* Intel Corporation and may not be copied or disclosed 

t except in accordance with the teras of that agreement. 

¥ 

#/ 

/k 

* This module builds the 204 paraneter block and passes the 

# address of it to the i9BC 206, 

x 

¥ note: this format procedure deduces max$sectors from the 

* DEVSUNITSINFOSBLOCK (duib.dev$gran). it does NOT check to see if 
+ the operator has set the switches on the controller correctly. 
+ sectors may be 128 or O12 bytes. 

+ 

#/ 


$include(:flixcomon. lit) 
$save nolist 
finclude(:flsxnutyp. lit) 
$save nolist 
Fincludedsflsxiotyp. lit) 
$save nolist 
Fincludet:¢lsxparaa. lit) 
$save nolist 
$includet:fiix20édv. lit) 
$save nolist 
Sinclude(:flsx20in. lit) 
$save nolist 
$include(:f¢fsxradsf. lit) 
$save nolist 
$includet(:¢lsxiors. lit) 
$save nolist 
$include(:flsxduib. lit) 
$save nolist 
Finclude(sfiixtrsec. lit} 
$save nolist 
$include(:ff:xexcep. lit) 
$save nolist 
Sinclude(:¢i:xioexc. lit) 
$save nolist 


$include(:flsxZ0ddc. ext} 
$save nolist 


$subtitle(format$206: Format track procedure’) 


{* 

¥ format$20é 

# format a track on the 206 

+ 

* CALLING SEQUENCE: . 

* CALL format$206 (base, iors$p, duibfp, ispb$p); 
% 

* INTERFACE VARIABLES: 

+ base - base address af board, 

* iors$p - 1/0 Request/Resuit St a pointer 
+ duib$p - painter to Device-Unit Information Black 
* iopb$p - 1/0 parameter block pointer. 

# 

* CALLS: 

# builds206sfatstable 

a send$204$i opb 

$ 
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EXAMPLES OF DEVICE DRIVERS 


erate PROCEDURE (base, iors$p, duib$p, icpbSp) REENTRANT PUBLIC; 


base 
iors$p POINTER, 
aus POINTER, 
Agente POINTER} 
DECLAR 
iors BASED iorsfp I(I$REQSRES$SEG, 
eee NTER 
foraat$info BASED formatsinfos FORMATS$INFOSSTRUCT, 
duib BASED duibfp DEVSUNITSINFOSBLOCK, 
iopb BASED OEE, ICSPARMSBLOCK$206, 
platter 
spindle BYTE, 
Surface BYTE, 
max$sectors BYTEs 


farmatfinfosp = iors. aux$p; 
IF forsat$info.track$nua > iZ206$TRACKSMAX THEN 
iors.status = ESSPACE: 
iors,actual = 03 
iors.done = TRUEs 


RETURN: 
END: 
Hatter = shrflors.unit, 2); /* 4 units/spindle #/ 
latter = iors.unit AND 493 Hs /* tas above } #/ 
nietics = formatfinfo. track$nue AND 00001H; /* select surface #/ 


iopb,inter = INTERSOQNSMASK OR FORMATSTRACKSON: 
ioph.cyl#add = shr(format$info.track$nue, t); /* ar = cylinder #/ 
lopb.rec$add = shr (format#info.track$nua "AND O200H, 2); /* set if over 254 cylinders #/ 
iopb.instr = foraatsop { 
shl (spindle, 4) QR 
shliplatter, 6) Oh 
sh! (surface, oes 


ioph.bufffp = Siopb. formatftable; 


TF duib.deySgran = 128 THEN 
maxtsectars = 34: 


/* 
eu not 128 then MUST be 512 byte sectors 
¥, 


max$sectors = 12; 


CALL build$20$fmt$tablei@iopb. formatétable, 
format$info, track$nua, 
format$infa, track#interleave, 
format$info.track$sken, 
format$info.fill¢char, 
maxSsectors); 


IF ee send$20o$iopb(base, @iopb) THEN 
4 ha beard did not accept the iopb so... 


0; 
iors.status = re 
iors.actual = 
iors.done = TRU: 


END format#204; 
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EXAMPLES OF DEVICE DRIVERS 


build$204$fat$table 
fill out format table 


CALLING SEQUENCE: 
CALL build$204$fat$table(bufsp, track, int$fact, skew, fill$char, aax$sectors); 


ents VARIABLES: 


_ 


Ce ee 


e - address of format table. 

trac - track to be formatted. 
int$fact ~ interleave factor. 
skew - squew from Wee sector one, 
fill$char - used to fill sectors. 
max$sectors - maximum number of sectors 

CALLS: 
«none? 


No error checking on skew, int$fact Pala if nonsense, the algoritha 


completes & formats the track in a strange manner. 
/ 


ee PROCEDURE (buf$p, track, int#fact, skew, fill$char,max$sectors) REENTRANT: 


ue POINTER, 
track WORD, 
int$fact RYTE, 
skew BYTE, 


fill $char BYTE, 

max$sectors BYTE; 
DECLARE 

5 BYTE, 


i BYTE; 
DECLARE 
fmt$tab BASED buf$e STRUCTURE { 
record$address 
fill char BYTE oF 


DO i = 9 10 (maxfsectors - 1); 
fmt$tab(i).recordfaddress = OFFHs 
; fat$tab(i). fill$char = fill$char; 
i 
s = skew MOD max$sectors; 
DO i= 1 TQ max$sactors: 
DQ re Alberts record$address <> OFFH; 
) MOD max¥secters; 
END; 


fat$tabisi.record$address = i; 
s = {5 + int$fact) MOD max$secto 
END: 


END build$204sfat$table; 
END x20btm; 


MODULE INFORMATION: 


CODE AREA SIZE = 0192H 4020 
CONSTANT AREA SIZE = OO00H 0D 
VARIABLE AREA SIZE = 0000H OD 
MAXIMUM STACK SIZE = 0028H 40D 


743 LINES READ 

0 PROGRAM WARNINGS 

0 PROGRAM ERRORS 
DICTIQNARY SUMMARY: 

F6KB MEMORY AVAILABLE 

{3KB MEMORY USED = 13%) 

OKB DISK SPACE USED 


END OF PL/M-86 COMPILATION 
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EXAMPLES OF DEVICE DRIVERS 


PL/M-86 COMPILER ¥8274: 8274 terminal device driver 


Module Header 


iRNX 86 PL/N-86 V2.3 COMPILATION OF MODULE x8274 
QBJECT MODULE PLACED IN :F1:X8274.0BU 
COMPILER INVOKED BY: :LANG:pla@é :F1:X8274,P86 COMPACT OPTIMIZE(3) ROM PAGEWIDTH(132) NOTYPE 


oa thou oa 


$title(’x8274: 8274 terminal device driver’) 


$subtitle (‘Module Header ‘) 


/t 

# TITLE: ¥8274 

# 

* DATE: 27 FEB 84 

¥ 

* ABSTRACT: This module is the interface between the iRMX 84 

t Terminal Support, and the 9274 MPSC. It is a 

* rewritten version of a acdule of the same nane dated 
# 20 Jan 93. The fies was necessary to correct 
$ initialization timing probleas and to add support for 
* various timer devices, i.e. 8253-4, 80130, and 90186-8, 
# 

¥ LANGUAGE DEPENDENCIES: PLM84 COMPACT ROM 

#} 

it 

t INTEL CORPORATION PROPRIETARY INFORMATION 

t 

¥ This software is supplied under the terms of a 

* license agreement or nondisclosure agreement with 

# Intel Corporation and may not be copied or disclosed 

+ except in accordance with the teres of that agreement. 

+ 

#/ 


49274: D0; 


finclude(:fliycomon. lit) 
$save nolist 
finclude(:ffisxnutyp. lit) 
Fsave nolist 
$include(:ffixiotyp. lit) 
$save nolist 
$include(:fiixexcep. lit) 
$save nolist 


Sinclude(:fiixtssow, ext) 

$save nolist 
$included:flsxtstia.ext) 

'¢ 

f 

* External Declaration 

* for timer support procedure. 


+/ 

$SAVE NOLIST 
Fincludet:flixdelay. ext) 
$SAVE NOLIST 


$subtitle('Data structures and literals’) 
/t 


# 9274 register values 
#/ 


EXAMPLES OF DEVICE DRIVERS 


20 I DECLARE 
RO LITERALLY ‘OOH' 


! 
WR i LITERALLY ‘OLH', 
WR2 LITERALLY ‘02H, 
WRS LITERALLY ‘O3H', 
WR4 LITERALLY ‘O4H', 
WRS LITERALLY ‘OSH', 
WRG LITERALLY ‘O6H', 
WR7 LITERALLY ‘O7H', 
RRO LITERALLY ‘OOH’, 
RRL LITERALLY ‘O1H', 
RR2 LITERALLY ‘02H'; 
/* 
* 9274 command values 
+/ 
21° tt DECLARE 
NULL_CMD LITERALLY ‘QOH’, 
NULL VECTOR LITERALLY ‘90H’, 
RESET EXT INT LITERALLY ‘L0H', 
CHANNEL RESET LITERALLY ‘L8H', 
ENABLE INT NEXT_RX LITERALLY ‘20H’, 
RESET_TX_IAT LITERALLY ‘28H', 
ERROR RESET LITERALLY 30H‘, 
END _OF_INT LITERALLY ‘38H’; 
/# 
* §274 write register commands, 
#/ 
Z2- A DECLARE 
WRI INIT LITERALLY ‘O14H', /# int on all Rx chars and 
# special conditions. 
* Parity affects vector, 
* variable vector, 
* Ty int enable, No 
* external int. 
$/ 
WRi_NO RX INT LITERALLY “Q04H',  /# disable fx interrupts #/ 
WAL NO_INT LITERALLY ‘OO4H', /# Disable Ry and Tx 
re 
WR2_ INIT LITERALLY ‘OO4H', /# non vectored int #/ 
WAS” INIT LITERALLY ‘OCH’,  /# Rx 8 bits/char, 
¥ By enable 
+/ 
WR3_RX DISABLE LITERALLY ‘OCOH’, 
WR4” INIT LITERALLY ‘O44H', /# LX clock, @ bit data, 
t ist stoop bit, no parity 
¥/ 
WRS TX_ENABLE LITERALLY ‘OEAH’,  /# Tx 8 ie data, 
* Ty enable RTS. enable 
#/ 
WRG TX DISABLE LITERALLY ‘OE2H", 
WRS"DTR ON LITERALLY ‘GESH', 
WRS_DTR_OFF LITERALLY ‘OAH’; 
it 


. Status register bit masks 
23! DECLARE 


VECTOR MASK LITERALLY ‘QEQH', 
TEST VECTOR LITERALLY ‘OASH', 
INT PENDING LITERALLY ‘002H', 
NOQ_INT_VECT LITERALLY “OICH’, 
RX_CHAR_RDY LITERALLY ‘OOLH', 
TX BUFFER EMPTY LITERALLY ‘QO4H", 
i8274$INPOTSERROR LITERALLY ‘O70H': 


24 
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EXAMPLES OF DEVICE DRIVERS 


"OSH + MORESINTERRUPT ° 
"OLH + MORESINTERRUPT 
‘O2H + MORESINTERRUPT © 


/% 
# Flags values 
*/ 
1 DECLARE 
EVENSMODE LITERALLY ‘O003H', 
ODDSNODE LITERALLY “SOLH', 
NOSPARITYSMODE LITERALLY ‘OO0H', 
INSPARITYSMASK LETERALLY ‘9390H", 
QUTSPARITY$MASK LITERALLY ‘{COH', 
STRIPSINPUTSPARITYSMQDE LITERALLY ‘O00H', 
PASSSINPUTSPARITYS$MODE LITERALLY ‘O10H', 
EVENSINPUTSPARITY$MQDE LITERALLY ‘920H’, 
QDDSINPUTSPARITYSNODE LITERALLY ‘30H’ 
SPACESOUTPUTSPARITYSMQDE = LITERALLY "OOOH", 
MARKSOUTPUTSPARITYSMODE LITERALLY ‘O40H', 
EVENSOUTPUTEPARITYS$NODE LITERALLY ‘980H', 
QODSQUTPUTSPARITYSMODE LITERALLY “OCOH', 
PASSSOUTPUTSPARITYSMODE LITERALLY ‘100H", 
OUTSPARSCHECK LITERALLY ‘OBGH's 
{% 
# Baud rate values 
#/ 
{ DECLARE 
HAKDWARESBAUDSSELECT ©=LITERALLY ‘0', 
AUTOSBAUDSSELECT LITERALLY ‘3', 
QUTSBAUDSSAME LITERALLY ‘1's 
it 
e interface to terminal support 
+ 
L DECLARE 
MORES INTERRUPT LITERALLY ‘O8H", 
NOSINTERRUPT LITERALLY “OQH" 
DELAYS INTERRUPT LITERALLY 
INPUTS INTERRUPT LITERALLY 
GUTPUTSINTERRUPT LITERALLY 
RINGS INTERRUPT LITERALLY 


in 


CARRIERSINTERRUPT 


# fontraller Bata Structure 


&/ 
I DECLARE 
TS$CORTA = LITERALLY "STRUCTURE ( 
TS$CDATAI, 
TS$CDATAZ) ' 
BECLAR 
TOSCDATAL LITERALLY ‘ics$datassegment 
status 
interrupts$tyse 
interruptingsunit 
dinfoto 
driver$cdatafp 
TSSCDATA2 LITERALLY ‘reserved (34) 


udata({) 
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‘OSH + MORESINTERRUPT ’ 
LITERALLY “O4H + NORESINTERRUPT '; 


ee a ey 


BYTE 
POINTER 
POINTER’, 
BYTE, 
BYTE 3 


4 
el 
eo 


EXAMPLES OF DEVICE DRIVERS 


{t 
€ Unit Data Structure 
#/ 
DECLARE 
TS$UDATA LITERALLY ‘STRUCTURE ( 
rauntae 
TS#UDATA 
TeHUDATASS 
DECLARE 
TSSUDATAL LITERALLY ied 
terafflags 
infrate 
outfrate 
scroil $number 
translation{87) 
TS$UDATAZ LITERALLY ‘inputfcontrol#table (33) 
unlt$nuaber 
TS$UDATAS LITERALLY ‘fill (891) 
{tk 
< 8274 Device information Structure 
+ 


CLARE 
1B274$CONTROLLERSINEO LITERALLY ‘STRUCTURE! 


DECLARE 
182745 1NFOS1 LITERALLY ‘tiller (12) 
iS274$INFOQS2 LITERALLY ‘ch_a_data_ port 
ch_a_status port 
ch_b data port 
ch_b status port 
iG274$INFO$3 LITERALLY ‘ch a_in_rate port 


ch_a_in_rate coun 
ch_a_in rate freq 
iQ274$INFO$S4 = =oLITERALLY ‘ch a out _rate_oort 


POINTER, 


i274 NFOS1, 
iG274$ INFOS? , 
iG274S1NFOSS, 
i@2743INFOS4, 
iB274$NFOSS, 
LA 27ASINF OSS, 
iB274$1NFOST! ' 


oy 


WORD , 
WORD, 
WORD, 
WORD, 
WORD’ , 
WORD, 


ch_a_in-rate ced_o port Agno, 
er TE 


DHORD', 
WORD, 


ch_a_ovt_rate_cnd <port WORD, 


ch_a_ out_rate count 
. ch_a_out_rate freq 
iS274$INFO$S = LITERALLY ‘ch_b_in_rate_port 


BYTE, 
DWORD 
WORD, 


ch b in_rate cd port WORD, 


ch_b_in_rate count 
ch_b_in-rate freq 
iG274$INFO$S = =LITERALLY ‘ch b cut_rate_port 


er 4HYTE, 


DWORD', 
WORD, 


ch_b cut rate cad -port WORD, 


ch_b out rate count 

ch_b out_rate freq 
13274$ INFOS? LITERALLY ‘ch a_timer_type 

ch_b timer type 
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DWORD: 
BYTE, 
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EXAMPLES OF DEVICE DRIVERS 


$subtitle(i8274Finit’) 


/ 
TITLE: i8274$init 


CALLING SEQUENCE: 
CALL i8274$init(cdatasp) ; 


INTERFACE VARIABLES: 
cdata$p POINTER to controlier data 


CALLS: 
none 


ABSTRACT: 
Initializes the 8274 chip. 


io de Odeo 


see, 


18274$inits PROCEDURE (cdatadp) REENTRANT PUBLIC: 


DECLARE 
cdatasp POINTER 
cdata BASED cdatage TS$CDATA: 
DECLARE 
18274$infosp POINTER 
i8274finfo BASED  18274$intogp i8274$CONTROLLERS INFO: 
DECLARE 
pert WORD; 
i* 
4 Get the configuration info 
# 


iB274$infosp = cdata.dinfogp; 
it 
* Initialize driver data area (10 bytes in length) 
$/ 
CALL setb(OFFH, cdata.driverg$cdatato, 10); 


it 


* Reset and Initialize the 8274, 
x/ 
DISABLE: 
port = 18274$into.ch_a status port; 
CUTPLUT (port) = Wha: ‘*# point to WRO #/ 
CALL delay {10is /# insure delay between cutouts 
OUTPUT (port) = CHANNEL RESET; /# reset channel A ¥/ 
CALL delay{19); /* insure delay between outputs 
ENABLES 
DISABLE; 
port = 18274$info.ch_b status ports 
QUTPUTiport) = WROs /* point to WRO #/ 
PALL delay(10); /* insure delay betwes sutputs 
QUTPUT{port) = CHANNEL RESET; /# reset channel A #/ 
CALL delay (10); /* insure delay between outputs 


he my 
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EXAMPLES OF DEVICE 


DISABLE; 
ee = WR4: /t 
CALL delay(10); [* 
ee ht = WR4_INIT; /* 
CALL delay(1d); /* 
ENABLE 
SABLE} 
Ne es = WRS; it 
CALL delay(10); it 
id Bt = WRO_TX_ENABLE; = /# 
CALL delay {{0); /* 
ENABLE; 
DISABLE; 
nN thy = WRI; it 
CALL delay({a)s /* 
uae eee = WRS_INIT; /* 
CALL delay (19); it 
ENABLE: 
DISABLE; 
ee ee = Wi; it 
CALL delay{19); {t 
QUTPUT (port) = WRI _NO_INT; /* 
Pay itd) /t 


CALL de 
ENABLE; 


DISABLE; 


port = 18274$info.ch_a_status ports 


QUTPUT (port) = WR4: it 
CALL delayi1); it 
QUTPUT (port) = WR4_INIT; {k 
CALL delay i!0); it 
© § 

DISABLE: 

OUTPUT (port) = RS; it 


CALL defay:19); it 
ede = WRO_TX ENABLE; = /# 


CALL delay(1d); it 
ENABLE; 
DISABLE: 
QUTPUT{port) = HRS; it 
CALL delay(10)s /* 
OUTPUT {port} : WRS_INIT; it 


CALL delay (10): it 


bade 


DISABLE; 


OUTPUT (cort) = WRI 
PALL delay (1d); /* 
OUTPUT (port = WRL_NO_INTs /* 
CALL delay{l0); it 
ENABLE; 

DISABLE 


port = 18274$info.ch_a status ports 


QUTPUT (port) = WR2; it 
CALL delay(10); it 
QUTPUT (port) = WR2_INIT; It 
CALL delay({)); it 


NABLE; 
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DRIVERS 


point to WR4 #/ 

insure reg! between outputs */ 
initialize WR4 #/ 

insure delay between outputs #/ 


point to WRO */ 

insure cea between outputs #/ 
initialize WRS - Tx enabled t/ 
insure delay between outputs #/ 


ooint to WRS #/ 

insure delay between outputs #/ 
initialize WR3 - Rx enabled #/ 
insure delay between outputs #/ 


point to WRI #/ 

insure ee) between autputs #/ 
initialize WRI - Interrupts disabled #/ 
insure delay between outputs #/ 


point ta WR4 #/ 

insure delay between QUTPUTs #/ 
initialize WR4 +/ 

insure delay between CUTPUTs #/ 


point to WRS #/ 

insure se! between QUTPUTS #/ 
initialize #WR5S - Tx enabled #/ 
insure delay between QUTPUTs #/ 


point to WRS #/ 

insure delay between QUTPUTs #/ 
initialize WR3 - Rx enabled */ 
insure delay between QUTPUTs #/ 


/* point to WRI #/ 


insure delay between QUTPUTs */ 
initialize WRI - Interrupts disabled #/ 
insure delay between QUTPUTs #/ 


point to WRZ #/ 

insure delay between GUTPUTs #/ 
initialize WR2 - non vectored int #/ 
insure delay between OUTPUTs #/ 
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EXAMPLES OF DEVICE DRIVERS 


DISABLE; 
port = :8274#inta.ch_b status port; 
OUTPUT (port = WR2s /* point to WR2 #/ 
CALL delay (10); /* insure delay between QUTPUTs #/ 
QUIPUT (port) = = NULL_VECTOR: /# initialize WR2 - non vectored int #/ 
5 
/t 
# Set the pay vector in R2B to some value, and then read it 
# back to see if the chip is really there, then set to the desired 
* value. 
#/ 
cdata.status = ESO0K; 
QUTPLT (port) = WR2s /* point to WR2 #/ 


CALL delay (10); /* insure delay between QUTPUTs #/ 
GUTPUT (port) = TEST_VECTOR; /* interrupt vector for RR2B #/ 


CALL TIME(1O); 


QUTPUT (port) = RR2: /* point to RR2 #/ 
CALL delay(19); /* insure delay between OUTPUTS #/ 


Se a AND VECTOR MASK) <> (TEST_VECTOR AND VECTOR MASK) 
cdata. status = ESO; 

CALL TIME({0}; 

QUTPUT (port) = HR2; /# point to WR2 #/ 

CALL delayilO); /# insure delay between QUTPUTs #/ 

QUTPUT(oort) = NULL_YECTOR; /* null interrupt vector for RR2B #/ 

CALL TIME( 19); 


QuTPUTisart) = RR2; /* point to RR2 #/ 
CALL delay (10); f# insure delay between CUTPUTs ¥/ 


IF (INPUT‘ port) AND VECTOR MASE) <> 
THEN 
cdata, status = ESQ; 
END i8274$inits 


Fsubtitlet id274$setun ’) 


TITLE: i9274¥cetus 


ALLING SEQUENCE: 
FALL i8274$setupiudatagp): 


INTERFACE VARIABLES: 
udataso POINTER to unit data 


CALLS: 
none 


ABSTRACT: 
Initializes the baud rate generator to the configured 
rate, and sets up the 8274 for asychronous acde, 
divide by 16, 8 data bits, { stop 
bit: parity generation per configuration. 
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EXAMPLES OF DEVICE DRIVERS 


i8274$setup: PROCEDURE (udata$p) REENTRANT PUBLIC; 


DECLARE 
udatadp POINTER, 
udatasp$a STRUCTURE { 
offset WORD 
base SELECTOR) AT(@udatagp) , 
cdata BASED udata$pso.base TS$CDATA, 
udata BASED udata$p TS#UDATA 
DECLARE 
18274$infoge POINTER 
i8274$infa BASED  id274$intasp i9274§CONTROLLERSINEO; 
DECLARE 
chip POINTER, 
ch BASED chp STRUCTURE ( 
data port WORD, 
status port WORD }, 
ch_rate_p POINTER, 
ch_rate SASED ch_rate_p STRUCTURE ( 
in_port WORD, 
eee ee WORD, 
in_counter BYTE 
in freq pword, 
out part WORD, 
ae ice WORD, 
gut _counter BYTE 
cut freq DWORD) , 
driverfdatasp POINTER, 
driver$data BASED driver$data$p STRUCTURES 
ch_afingrate WORD, 
ch_afout$rate WORD, 
eee BYTE, 
ch b$ingrate WORD, 
ch_b¥outfrate 40RD 
ch bSparity BYTE| ; 
DECLARE 
temp HYTE, 
port HORD, 
cut cad BYTE, 
parity$aade BYTE, 
timerdtype BYTE, 
ratefcount WORD, 
ingrate WORD, 
out$rate WORD, 
parity RYTE} 


i82744intosp = cdata dintoto; 
driver$datafo = cdata,driverfcdatagp; 


IF udata.uniténumber = 9 THEN 


wy 


ch_p = @i8274$into.ch_ a_data_port; 
ch_rate_p = @i8274$infa.ch_a_in_rate port; 
timer$type = 


ingrate 


i8274$info.ch a timer type; 


driver$data.ch adintrate: 


out$rate = driverf$data.ch afout$rate; 
parity = driver$data.ch_afparity; 


Eust 


EXAMPLES OF DEVICE DRIVERS 


DO; 
fib od ch_p = @18274$info.ch 6 data port; 
152 33 ch_rate_p = @i8274$info.ch_tin_rate_port; 
i ae timer$type = i8274$into.ch t timer type; 
154 3 in$rate = driver$data.ch_bFingrate; 
1553 out$rate = driver$data.ch biout$rate; 
154 3 parity = driver$data.ch_bSparity; 
ye END; 
138 2 out_cad = WRS_TX ENABLE: 
it 
# Initialize the input rate generator if the baud rate has changed, or 
1 if a baud rate scan is in progress, and if it’s programmable. 
# 
{392 IF (in$rate ¢> udata.infrate) AND 
A <> 0) AND ‘udata.in$rate ¢> HARDWARESBAUDS$SELECT) 
1a) 2 00; 
{61 3 aA udata.ingrate <= GUTQSBAUDSSELECT THEN 
142 3 ; 
1634 ” ratescount = SHR(19200, (udata.in$rate-1)#3); 
164 4 out_cad = WRG TY DISABLE: 
{65 4 END; 
165 3 ELSE 
DO; 
{47 4 rate$count = udata.ingrate; 
168 4 ingrate = udata.indrate; 
169 4 END; 
{t 
* The initial timer value is the timer inout frequency 
ae by the configured baud rate. 
+ 
179) 3 temp = FALSE: 
v2 ee IF (ch rate.in freq MOD ratefcount) = SHRiratefcount,{) THEN 
172 3 tenp = TRUE; 
tig. 3 ratefcount = (ch_rate.in_freq / rate$count); 
174 TF temp THEN 
as oS ratescount = rate$count + {; 
174 3 CALL set$baud$ratefcountich rate.in_cad port, 
ch rate.in_port, 
timerstype, 
ch rate.in counter, 
ratefcount!; 
ioe 3 END: 
it 
* initialize the output baud rate generator, if there is one, and it has 
7 changed, and it’s programmable. 
* 
IBS 22 IF (qut$rate <? udata,out$rate) AND 
Sa {> 0) AND (udata.cut$rate <> HARDWARESBAUDSSELECT) 
179 2 0; 
fag IF udata.cutfrate <> GUTSBAUIDSSAME THEN 
{gi 03 DQ; 
182 4 temp = FALSE; 
183 4 IF eT EE PEADU SEES MOD udata.out$rate) >= SHRiudata.cut$rate,!) 
1d4 4 temp = TRUE: 
185 4 ratefcount = (ch _rate.out_freq / udata.out#rate); 
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EXAMPLES OF DEVICE DRIVERS 


IF temp THEN 
ratefcount = ratetdcount + 1; 
END; 


out$rate = udata.out$rate; 


[t 
# The initial timer value is the timer output frequency 
ee by the configured baud rate. 

t 


CALL set$haud$ratescount(ch_rate.out_cmd port, 
chorate.out port, 
timer$type, 
ch_rate.out_counter, 
rate$count) ; 


END; 


figure cut the parity control part of the node word, 
IF (udata.term#flags AND QUTSPARITYSMASK) = EVENSQUTPUTSPARITYSMODE THEN 
parity$mode = EVENSMODE; 
D0; 
ap na AND QUTSPARITYSMASK) = QDDSQUTPUTSPARITYSMODE 
eee = ODDSMODE; 
parity#nmode = NOSPARITYSMODE; 
END; 


sort = cn status port; 

/* 

* If anew parity is specified, set up this 8274 channel accordingly. 

#/ 

Hi parityfmode <> parity THEN 

parity = paritySmode; 

QUTPUT (port) = WR4; /* point to WR4 4/ 
CALL delay(iOis /* insure delay oetween QUTPUTs #/ 
OUTPUT (sort) = WR4 INIT GR parity$mode; 


CALL TIME(10); 


END: 

He ee = WROs /# point to WAS +#/ 

CALL delay(19); /t insure delay between outputs #/ 
OUTPUT port) = out cmd; 

CALL TIME(10); 

deen = WRG: /*# point to WRS #/ 

CALL delay (14); /* insure delay between outputs #*/ 
hy = WR3_INIT; 

CALL delay (19); /# insure delay between outputs #/ 
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EXAMPLES OF DEVICE DRIVERS 


/t 
* Throw away any chars fro baud rate search. 
t 


216. 2 DO WHILE (INPUT{ch.status port) AND RX_CHAR_RDY) <> 0; 
247) 3 temp = INPUT(ch.data_port); 
2180 3 CALL delay(10); /* insure delay between outputs #/ 
ae: 5 ND; 
t 
# If the 8274 is ready for output, tell the terminal support 
* to send a char. 
#/ 
220 2 CALL delay (10); /# insure delay between outputs #/ 
22° 2 IF (INPUTich. status port) AND TX BUFFER_EMPTY) <> 0 THEN 
ae CALL xts$set$output$wai ting (udatagp) ; 
[t 
ae Ty and Rx interrupts row, 
t 
bes. 2 CALL delay (10); /* insure delay between outputs #/ 
224 2 QUTPUT (port) = WRI; /# point to WRI #/ 
220° 2 CALL delay (19); /* insure delay between outputs #/ 
226 «2 QUTPUT{port) = WRL_INIT; 
237 9 


END 18274$setup; 
$subtitle('18274$check ') 


i 


TITLE: i182745check 


CALLS: 
none 


INTERFACE VARIABLES: 
cdata$p POINTER to controller data 


CALLING SEGUENCE: 
ch = i8274$check(cdata#o) 


ABSTRACT: 

Term$check procedure, connected to 9274 input interrupt. 
Gets input char, strips off parity if required, and sets 
up flags for terminal support. 


eo ee ee ee ee ee ee 


/ 
228°. 1 1d274$check: PROCEDUREicdata$p) BYTE REENTRANT PUBLIC; 
Zo) DECLARE 


cdatasp POINTER 
cdata BASED cdatatp TS$CDATAs 
230 2 DECLARE 
iB274$info$p POINTER 
i8274$info BASED i9274$infofp  i8274$CONTROLLERSINEO, 
udatasp POINTER, 
udatatpso STRUCTURE ¢ 


offset WORD 
base SELECTOR ) AT (@udatagp), 
udata BASED udata$p TSSUDATA; 
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EXAMPLES OF DEVICE DRIVERS 


DECLARE 
ch p POINTER, 
ch BASED chp STRUCTURE ( 
data port WORD, 
status port WORD ) 
claret P TER, 
ch_rate BASED ch rate_p STRUCTURE ( 
in_port WORD, 
in_cad_port WORD, 
in_counter HKYTE 
in_ freq DWORD, 
out port WORD, 
out_cad_port WORD, 
out counter BYTE 
out "freq  OWORD ); 


DECLARE 
unit EYTE, 
vector BYTE, 
dummy BYTE, 
faund$rate BYTE, 
i WORD, 
char BYTES 


18274Sinfofp = cdata.dinfofp; 


ik 

find out what caused the interrupt by reading RR2B 

* 
OUTPUT (i8274$info.ch_b status port) = O02H; 
CALL delay(3}s /# insure delay between outputs #/ 
vector = INPUT {i8274$info.ch_b status part); 
CALL delayi20); /* insure delay between autputs #/ 
TF ({vector &ND NO_INT_VECT) = NO_INT VECT) AND 
‘a (LINPUT(i8274$info.ch_a_status port) AND INT_PENDING) = 0) THEN 
Hiye 


~’ eSdatainterrupt$type = NOSINTERRUPT: 
RETURN char} 
END: 


IF (vector AND 19H) = 10H THEN 
ch_p = @18274$info.ch_a_data port; 
ch_rate_p = i9274$info.ch_a in_rate port; 
ai; c$data.interruptinggunit = {5 
ELSE 
DO; 
ch_p = @i8274$info.ch_ b_data_port; 
ch_rate p = 8i18274$info.ch_b in_rate_port; 
c$data.interrupting$unit = 1; 


END; 
it 
* Set _ udatatp to ee to the interrupting units data. 
# { that is, add 1024 to the pointer for each unit 
+/ 


udata$p = &cdata.udata; 
udatafp$o.offset = udatatp$a.aftset + 
SHL (DOUBLE (cdata.interruptingfunit) ,10)3 


vector = (SHR(vector,2) AND 03H); 
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EXAMPLES OF DEVICE DRIVERS 


/* 


* Modify the vector so that Special Rx Condition interrupts 
re handled in the Rx Char. Available case. 
$ 


IF vector = 3 THEN 
DQ; 
vector = 23 
OUTPUT(ch. status port) = ERROR RESET; 
‘ CALL delay(2); /# insure delay between outputs */ 
H 


i vector = 2 THEN 


j : 
/* Ry Char. available #/ 


char = INPUTich.data port); 


it 

# Tf in auto baud rate search, check character for 
* an identifiable baud rate 

*/ 


Wf udata-ingrate <= AUTOSBAUDSSELECT THEN 


" char = char AND O7FHs 
IF (char = 35H) THEN 
faund$rate = 0: 
ELSE 
DO; 
IF char = 64H “HEN 
found$rate = !: 
SE 
DO; 
IF char = 78H THEN 
pues = 2} 
DO; 
TF char = 0 THEN 
[* 
* Go to next Daud rate range and 
* condition terminal support to call setup 
* in about {50 as, 
*/ 
udata,infrate = udata.ingrate + 1; 
IF udata,ingrate > AUTOSBAUDSSELECT THEN 
udata,ingrate = {3 
QUTPUT{ch. status port! = WRI: 


CALL delay(10); 7# insure delay between outputs */ 


QU"FUT (ch. status port) = WRI NO RY INT; 


CALL delay(10): 7# insure delay between outputs #/ 


cdata.interrupt$type = DELAYSINTERRUPT: 
QUTPUT(ch.status port) = WR; 


CALL delay{10); 7# insure ay between outputs #/ 


QUTPUT{ch.status port) = HRS AX_DISABLE; 


CALL ape 7+ insure delay between autputs #/ 


fs CALL TIME(IQ); #/ 


OUTPUT {i8274$info.ch_a status port) = END OF INT; 


RETURN char; 

END: 

ELSE 

DQ; 
IF udata.ingrate <} 3 THEN 
DO t 


cdata.interrupt$type =. MORESINTERRUPT 
RETURN char} 

END); 

ELSE 
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EXAMPLES OF DEVICE DRIVERS 


DQ; 
udata.ingrate = 119; 
GUTPUT(ch.status port) = WRI; 
CALL delay(10); 7# insure delay between outputs #/ 
OUTPUT (ch. status port) = WAL NO URX INT; 
CALL delay{10); 7# insure defay between outputs #/ 
cdata.interruptstype = DELAYSINTERRUFTs 
QUTPUT{ch.status port) = WRS: 
CALL delay(10); 7# insure gel ay between outputs #/ 
OQUTPUT(ch. Status port) = WR3 RX DISABLE; 
CALL ieee 7# insure delay between outputs #/ 
/* CALL TIME(IG); #/ 
OUTPUT (i8274$info.ch_a_status_port) = END OF _INTs 
RETURN char; 


{t 
# (Calculate recognized baud rate 
*/ 


udata.ingrate = SHR(19200, (udata.in$rate-1) # 3 + found$rate); 
QUTPUT(ch. status port) = WRI; 
CALL delay{10); 7* insure delay between cutputs #/ 
QUTPUT(ch. status port) = WRE_NQ RX INTs 
CALL delay(10); 7# insure delay between outputs #/ 
cdata.interrupt$type = DELAYSINTERRUPT: 
QUTPUT ich. status port) = WR3: 
CALL delay{10); 7# insure coat between outputs #/ 
OUTPUT (ch. status port) = WR3 RX DISABLE: 
CALL ae ae 7* insure deTay between outputs #/ 
/# CALL TIME({O)3; #/ 
QUIPUT (i: 8274$into.ch_a_status port) = END OF INT; 
RETURN char} 

END; 


it 
i check input parity mode & strip aarity if desired 
¥, 


IF Se ia AND INSPARITYSNASE) <> POSSSINPUTSPARITYSMODE 


DO; 
IF Patera AND INSPARITY$MASK) = 
STRIPSINPUTSPARITY$MODE THEN 
char = char AND 07th: 
eL$ 
DQ: 
Hi (udata.term$flags AND QUT$PARSCHECK) <> 0 THEN 
“7.2 
GUTPFUTIch.status port) = RRL; /# point to RRI #/ 
CALL delay(3); 7# insure delay between outputs #/ 
iF cae AND iS274$INFUTSERROR) <3 9 


D0; 
char = char OR O80H; 
OUTPUT ch. status port) = ERROR_RESET; 
CALL delay(10); 7# insure delay between outputs #/ 
QUTPUT (ch, status port) = WR3; 
CALL delay(10); 7# insure delay between outputs #/ 
QUTPUT(ch. status port) = WR3 INIT; 
END: 
END; 
ELS 
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EXAMPLES OF DEVICE DRIVERS 


DO: 
IF Eee ta AND INSPARITY$MASK) = 
a EVENSINPUTS$PARITYSMODE THEN 


b] 
dumay = 05 
char = char OR duamy; 
IF PARITY THEN 
char = char AND O7FH; 


SI: 
char = char OR OB0H; 


dumay = 3 
char = char OR dumay; 
TF MOT PARITY THEN 
sad = char AND O7FH; 


‘char = char OR OBOH; 


QUTPUT (2 9274$info.ch_a status port) = END OF INT; 
cdata.interrupt$type = INPUTSINTERRUPT: 


END: 
ELSE 
DQ; 
IF vector = % THEN 
DQ; /* Tx Buffer eapty +/ 


OUTPUT (ch, status port) = RESET TX_INT; 

CALL celay(3); /* insure delay between cutouts #/ 
cdata.interrunt$type = QUTPUTSINTERRUPT; 

OUTPUT (18274finfc.ch_a status port) = END OF_INT; 


END; 
ELSE 
DO; /* Ext/Status Change #/ 
QUTPUT(ch. status port) = RESET EXT INT; 
cdata.interrupt$type = MORESINTERRUPT: 
CALL delay(3); /* insure delay between outputs #/ 
QUTPUT(i$274$in¢o.ch_a status port) = END OF INT; 
‘ END; /# Ext/Status Change #/ 
i 


RETURN char; 


END 182748check; 
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EXAMPLES OF DEVICE DRIVERS 


$subtitle('i8274$answer ‘) 


/* 
* TITLE: 18274$answer 
# 
# CALLING SEQUENCE: 
% CALL 19274$answer (udata$p) ; 
t 
# INTERFACE VARIABLES: ; 
# udata$p POINTER to unit data 
¥ 
* CALLS: 
¢ none 
t 
* ABSTRACT: 
* Sends a mode word to the 8274 to place DIR active. 
# 
*/ 
i8274$answer: PROCEDURE(udata$p) REENTRANT PUBLIC; 
DECLARE 
udatatp POINTER, 
udatatp$o © STRUCTURES 
offset 
base SELECTOR) ) AT(@udatagp) , 
cdata BASED udatatpfo.dase TS#CDATA, 
udata HASED udatagp TSSUDATAs 
DECLARE 
i82744infosp POINTER 
i9274$info PaASED i82744infotp i927 4§CQNTROLLERSINED: 
DECLARE 
chp POINTER, 


ch BASED ch_p STRUCTURE ¢ 
data “port WORD, 
status _port WORD }s 
i8274¢infasp = cdata.dinto$p; 


IF udata.unitfnumber = 0 THEN 
chp = €19274$info.ch_a_data_port; 


‘chp = @i8274#info.ch_b data port; 

QUTPUT(ch. status port) = WR; 

CALL delay{10); /* insure delay between cutputs +/ 
QUTPUT (ch. status port) = WRS_DTR_ON; 


END 18274$answer; 
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EXAMPLES OF DEVICE DRIVERS 


$subtitle(’i8274$hangup ') 


/ 
TITLE:. 18274$hangup 


CALLING SEQUENCE: 
CALL i8274$hangup (udata$p) ; 


INTERFACE VARIABLES: 
udata$p POINTER to unit data 


CALLS: 
none 


ABSTRACT: 
Sends a mode word to the 9274 to place DTR inactive. 


ee ee ee ee ee ee ee et 
aaa 


£ 
1d274$hangup: PROCEDURE(udatasp) REENTRANT PUBLIC; 


DECLARE 
udata$p POINTER, 
udata$p$o  STRUCTURE( 
offset WORD 


base SELECTOR) AT(@udatasp) , 
cdata BASED udatadp$o.base TSSCDATA, 
udata BASED udata$p TSSUDATAS 


DECLARE 
182744infosp POINTER 
i8274$info HASED  i8274$info$p 19274§CONTROLLERSINEO: 


DECLARE 
chp POINTER, 
ch BASED chp STRUCTURE ( 
data port WORD, 
status port WORD ); 


id274$infosp = cdata.dinfogp; 


IF udata.unitfnumber = 0 THEN 
ch_p = &i8274$info.ch_a_ data port; 


ELSE 
ch_p = @18274$info.ch b data_port; 

QUTPUTich. status part) = HRS; 

CALL delay(1); /* insure delay between outputs #/ 
QUTPUT ich. status port) = WRO_DTR_OFF; 


END id274$hangup; 
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$subtitle('i8274$out ') 


/t 

* TITLE: 19274$out 

* 

# CALLING SEQUENCE: 

t CALL 19274$out (udata$p char); 

¥ 

& INTERFACE VARIABLES: 

# udata$p POINTER to unit data 

¥ char RYTE to OUTPUT 

% 

# CALLS: 

t none 

¥ 

* ABSTRACT: 

* OUTPUTS a char to selected channel of the 8274, 
# Marking or spacing parity is handled here if enabled, 
€ and the char is sent out. 

¥ 


#/ 
414 18274$out: PROCEDURE (udata$p,char} PUBLIC REENTRANT: 


4152 DECLARE 
udata$p POINTER, 
udatafp$o  STRUCTURE{ 
of fset WORD 
base SELECTOR) AT(@udatasp) , 
cdata BASED udata$p$o.base TS$CDATA, 
udata  HASED udatatp TSSUDATA; 
4142 DECLARE 
18274$info$p POINTER 
id274$info BASED i8274#infos$s i9274$CONTROLLERS INFO; 
4172 DECLARE 


ch_p POINTER, 
ch BASED chp STRUCTURE { 
data port WORD, 
status port WORD ); 


Aig DECLARE 


char RYTE, 
node WORD; 
419 2 18274$infosp = cdata. dinto$p; 
az) 2 TF udata,unit$number = 0 THEN 
471 2 chp = @i9274$into.ch_a_data_port; 
MDS <72 ELSE 
chp = @18274$info.ch_b data port; 
A232 mode = udata.term#flags AND QUTSPARITYSMASK; 
pr fi Ir mode <= MARESOUTPUTEPARITYSMODE THEN 
252 DO; 
425 3 TF mode = MARKSQUTPUTSPARITYSMODE THEN 
427) 3 char = char OR 90h; 
428 3 BLoc 
char = char AND O7FK; 
429° 3 END; 
4yy 2 DUTPUT{ch.data_port) = char; 
a3l 2 END 19274$out; 
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EXAMPLES OF DEVICE DRIVERS 


Ssubtitle(‘19274$finish’) 


/ 


fe i ee i ee a! 


TITLE: 18274$¢inish 
CALLING SEQUENCE: 


CALL 18274$finish(cdatasp) ; 


INTERFACE VARIABLES: 


cdataSp - pointer to controller data. 


CALLS: 
none 


ABSTRACT: 


Procedure disables TX, RX and interrupts. 


DECLARE 


cdatas 


p 
cdata BASED cdatasp 


DECLARE 


18274$into$p 
18274$info BASED 


DECLARE 


/* 
f 


port 


Get the configuration info 


#/ 
i8z74finfosp = cdata.cinfoso: 


{* 
t 


*/ 


18274$intosp 


i 
18274$finish: PROCEDURE {cdata$p) PUBLIC REENTRANT; 


POINTER 
TSSCDATAS 


POINTER 
i B27A$ CONTROLLERS INFO: 


WORD; 


Disable the 8274 TX, RX, and interrupts. 


port = 


OUTPUT (port) = WRS; 

CALL delay(19); 

QUTPUT (port) = WRS_TY DISABLE: 
CALL delay (1); 


QUTPUT (port) = WR3s 
CALL delayi!0}; 
QUTPUT (port) = WRS_RX_DISABLE; 
CALL delay(id); 


QUTPUTiport} = WRI; 
CALL delay (10); 
QUTPUT‘port) = WRL_NO_INT; 


CALL delay(!0)s 


18274$info.ch_b status port; 


/* point to WRG #/ 

/# insure delay between 
f* disable Tx 

/# insure delay between 


/* point to WR3 +#/ 


‘# insure delay between ¢ 


/# disable Rx 
/* insure delay between 


/* paint to WRI #/ 

/* insure delay between 
/* disable interrupts 
/* insure delay between 


/*# point to WRS #/ 


part = i8274$infa.ch_a_status port; 
OUTPUT (port) = RS; 
CALL dela 


CALL delay (10); 


OUTPUT {port) = WR3; 

CALL delay(10); 

QUTPUT { ore] =’ WRI _RX_DISABLE; 
CALL ay (ld); 


OUTPUT (port) = WRI; 

CALL delay{10); 

GUTPUT (rt) = WRI _NO_INT; 
CALL delay{10); 


OUTPUT { fe = WRO_TX_DISABLE; 
del 


END 18274$finishs 


END x8274; 
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/* insure delay between 
/# disable Tx 
/* insure delay between 


/# point to WRS #/ 

/* insure delay between 
/#t disable Rx 

/# insure delay between 


/¥ point to WRI #/ 

/# insure delay between 
/# disable ae 
/* insure delay between 


outputs 


outputs 


outputs 


cutputs 


outputs 3 


outputs 


outputs 


outputs 


outputs 


EXAMPLES OF DEVICE DRIVERS 
MODULE INFORMATION: 


CODE AREA SIZE = O943H = 23710 
CONSTANT AREA SIZE = O000H OD 
VARIABLE AREA SIZE = 0000H OD 
MAXIMUM STACK SIZE = Q030H 43) 
1394 LINES READ 

Q PROGRAM WARNINGS 

Q PROGRAM ERRORS 


DICTIONARY SUMMARY: 
76KB MEMORY AVAILABLE 
Z2KB MEMORY USED = (22%) 
OKB DISK SPACE USED 


END OF PL/M-B6 COMPILATION 


1% 
t x8255.1it 
¥ 
# 8255 is programmed as follows: 
+ 
* Group A: Mode ! 
* Group 8: Node 0 
t 
f Port A and Lower Port C: OUTPUT 
* Port 8 and Upper Port C: INPUT 
t 
* Port C definition (bit 0 is LOB; bit 7 is MSB): 
t 
* Bit 0 - Character strobe to the printer 
* 1 - not used 
# 2 - not used 
¥ 3 - Character acknowledge from the printer is complete 
* 4 - Printer ready 
# 3 7 Paper out 
t & ~- Printer interrupt enable 
, 7 - (Character acknowledge from the printer 
7 
DECLARE 
MODESWORD LITERALLY  ‘OAAH', 
CHARSACKSCONPLETE LITERALLY  ‘O8H', 
PRINTERSREADY LITERALLY ‘10H’, 
PAPERSQUT LITERALLY ‘20H’, 
CHARSACK LITERALLY ‘BH’, 
INTSENABLE LITERALLY  ‘ODH', 
INTSDISABLE LITERALLY ‘OCH’, 
STROBESON LITERALLY ‘SIH’, 
STROBESOFF LITERALLY  ‘QOH's 
i+* 
# xpentr, lit 
. Common device driver information 
$ 
* levels interrupt level 
* priority: Priority of interrupt task 
* stackfsize: Stack size for interrupt task 
* datafsize: Device local data size 
# numfunitss Number of units on device 


Init device procedure 

Finished with device procedure 
Start device procedure 

Stop device procedure 

Device interrupt procedure 


* deyicedinit: 

* devicegfinish: 

* devicetstart: 

* device$ston: 

* devicesinterrupt: 
# 


DECLARE COMMONSDEVSINFO LITERALLY 


level WORD, 
priority BYTE, 
stack$size HGRD, 
data$size WORD, 
numsunits WORD, 
devicefinit WORD, 
deviceffinish WORD, 
devicegstart WORD, 
devicefstap WORD, 
devicefinterrupt WORD’; B-39 
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DECLARE i8255$INFO LITERALLY 


A$port WORD, 

B$cart WORD, 

C$oort WORD, 

Controlfpart WORD; 

DECLARE 

PRINTERSDEVICESINFO LITERALLY ‘STRUCTURE ( 
COMMONSDEVSINFO, 
iB255$ INFO, 
tab$control WORD)’; 


$save nolist 
/% 


# x206dv. lit ; 

f Defines literals for 206 driver 
r 

#/ 


— 


The iopb fields (first 9 bytes) must be first!! 
They are used later and the other procedures 
do not know of status or restore, 


Note that each spindle has up to 4 platters, and each 204 can support 
up to 4 spindles, Thus, there are 4 statuses: one for each spindle. 


Restore is used to indicate that there is a restore in progress. 
it ig set when a restore is started after a request returns an 
error which requires a restore to reset the drive. A new request 
is not started when there is a restore in progress, instead the 
interrupt routine starts the request and resets restore when 

fi restore finishes, 


CLARE 
IOSPARMSBLOCKS206 «LITERALLY ‘STRUCTURE ( 


inter BYTE, 
instr BYTE. 
r$count BYTE, 
cyl $add BLle, 
recfadd BYTE 

buf ftp POINTER, 
status (4) BYTE, 
restore BYTE, 
format$table(72) BYTE)’; 


it 
* defines nasks 
#/ 


DECLARE 
interfonFmask LITERALLY ‘OOBH', /# bit 4.:= la-bit data #/ 
interfofffmask LITERALLY ‘O18H', 
FORMATSTRACK SON LITERALLY ‘G40, 
12Q4$TRACE SMAX LITERALLY 690", /* 400 tracks # 2 surfaces #/ 
i Z0S$SECTORSMAX LITERALLY ‘36°, 
command$tusy LITERALLY ‘O80H'; 
1% 
* defines op-codes 
#/ 
DECLARE 
nosap LITERALLY ‘QOH’. 
seeksap LITERALLY ‘1H’, 
format fop LITERALLY ‘O2H', 
restorefop LITERALLY ‘O3H', 
readfop LITERALLY ‘O4H", 
verifysop LITERALLY ‘OSH’, 
writesop LITERALLY ‘O6H"; 
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[* 
* defines ports 
*/ 


declare 
eh D aoe ort LITERALLY ‘base’, 
result$type port LITERALLY ‘base + 1°, 
controller$stat LITERALLY ‘base + 2’, 
result#byte$part LITERALLY ‘base + 3’, 
interfstatfport LITERALLY ‘base + 4°, 
Pree Mae LITERALLY ‘base + 7’, 
lofsegtpor LITERALLY ‘base’, 
Hela aes LITERALLY ‘base’, 
lofatt$port LITERALLY ‘base + 1’, 
hisofé$part LITERALLY ‘base + 2°, 
start$diagnostic LITERALLY ‘base + 3°, 
reset$part LITERALLY ‘dinfo.base + 7’; 
$restore 


$save nolist 


f 
x20ain. lit 


206 Driver info 

Adds to the deviceasinfo and unit#into structures, 
using comacn device support and random access 
device support. 


or a ee ee) 


~~, 
baad 


Per device inforaation 


ene 
<— 


DECLARE 
T2OASDEVICESINFO LITERALLY ‘STRUCTURE: 
RADEVESDEVICESINED, 
base WORD) *; 
/% 
* Fer unit information 
#/ 


DECLARE 
T206UNTTSINFO LITERALLY ‘STRUCTURE (RADSUNITSINFO) 's 
$restare 


$save nolist 
it 
* x20ddc,ext 
#/ 
sand#20d$iopb: PROCEDURE (base, iopb$p) BOGLEAN EXTERNAL; 
DECLARE 
gase 


Lapb$p 
END send#204#iopb; 


WORD 
POINTER: 


frastore 
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$save nolist 
it 
# x20ddp.ext 
#/ 
io%206: PROCEDURE (base, iors$p, duibfp, iopb$p) EXTERNAL; 
DECLARE 
base WORD 
iorssp POINTER, 


duib$p POINTER, 
iopb$p POINTER; 
END io$206; 


frestore 


$save nolist 


/t 
* x20dfm.ext 
&/ 
format$206: PROCEDURE {base, iors$p, duib$p, iopb$p) EXTERNAL; 
DECLARE 
base #ORD 
iorssp POINTER, 
duib$p POINTER, 
Lopb$p POINTER: 
END format#204; 
frestore 


$SAVE NOLIST 
it 

* nsleep.ext 
#/ 


ragsleep: PROCEDURE! timesliait, 
exceptsptr } EXTERNAL; 


DECLARE time$limit WORD, 
except$ptr POINTER; 


END rg#sleep; 


$RESTORE 
fsave nolist 
/* 
* xcomon. lit 
t Nft-used literals. 
t 
$/ 
DECLARE 
BOOLEAN LITERALLY ‘BYTE’, 
TRUE LITERALLY ‘SFFH’, 
FALSE LITERALLY ‘900H', 
FOREVER LITERALLY ‘WHILE TRUE’, 
PTRSQVERLAY LITERALLY “STRUCTURE (offset WORD, base TOKEN) ', 
PSQVERLAY LITERALLY ‘STRUCTURE ‘(offset WORD, base WORD) 
STRING LITERALLY ‘STRUCTURE (length BYTE, char (1) BYTE)’, 
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[* 
; DWORD LITERALLY ‘POINTER’, 
# 
NOSTIMESLIMIT LITERALLY ‘OFFFFH', 
BYTESMAX LITERALLY ‘OFFH* 
WORDSNAX LITERALLY ‘OFFFFA' , . 
FIFOS@ LITERALLY ‘OOOH’, /* salect FIFO queueing #/ 
sae PRIO$G LITERALLY 'OQO1H’; /* select PRIQ queueing #/ 
restore 


$SAVE NOLIST 


it 
* xdelay.ext 
+/ 


/% 
* External Declaration for 
+/ 


delay: PROCEDURE(units) EXT 


DECLARE 
units 


END delay; 


frestore 


$save nolist 
it 


* xdrin¢.lit 

* Driver information ¢ 
$ 

£/ 


Random-access driver 


level: 

priority: 
stack#size: 
data$size: 
nunfunits: 
devicedinit: 
devicesfinish: 
device$start: 
devicegstop: 
cevicefinterrupt: 


Gs i I Ee is OO id 


/ 


DECLARE 

RADEVSDEVICESINFO LI 
Bae 
priori 
eracksat ie 
data$size 
numgunits 
devicesinit 
davice$finish 
devicesstart 
device$stap 
devicesinterrupt 


Delay Procedure. 
ERNAL; 


BYTE; 


or common and random access devices. 


information 


Interrupt level 

Priority af interrupt task 
Stack size for interrupt task 
Device local data size 

Number af units on device 

Tnit device procedure 

Finished with device orocedure 
Start device procedure 

Stop device procedure 

Device interrupt procedure 


TERALLY 
HW 
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t 
* Unit info for radev 
t 


* track$size: Size in yee of track. Used for calculating 

+ track/sector. Requests to device will not cross 
¥ track boundaries, 

yaa R Number of tiges ta retry on a soft [@ error. 

¥ 


CLARE 
RADSUNITSINFO LITERALLY 


‘track$size WORD, 
maxgretry WORD, 
cylinder$size WORD; 


$restore 


$save nolist 


it 
* xduib. lit 
t Device-Unit Information Block definition. 
t 
&/ 
it 
# fame: ASCII name of dev-unit, null padded 
& fiiesdriver: Hitti) ==) ¢ile-driver (i+!) 15 ok for this device. 
* See idevag.pla 
# functs: From EPS, bit 1 =*) function(1) supported by the driver. 
* flags: For 215 only. See EPS. 
¥ functions are FSFIRMAT, FSREAD, etc. 
& dev$gran: device granularity in bytes. 
* dev$size: size (in bytes) of device-unit 
+ device: device number/device code 
* units device specific number of controller sub-unit ({1.¢., 
f for a 204, couid be 0,1 to indicate different drives) 
* devfunit: unique number identifying a device/unit pair for device 
+ ailocation purpases 
# initdic: driver procedure for initializing driver 
* finishfio: driver procedure for turning ateideatiecating driver 
* queuetio: driver procedure for queueing 1/0 requests 
* cancel $ia: driver procedure for cancelling I/0 requests 
# deviceginfosp: device specific 1iformation cointer. 
* unitsinfods: unit specific information pointer. 
* updatestimeout: time (ticks) before update on this unit 
* numfbufters: umber of ee ean buffers for this unit 
# oriority: service task ariority. 
* fixedbundate: boolean to indicate use of wal! clock updates. 
* nax$butters: maxinun no. of buffers for device (used by £105} 
ffi filler byte 
£ 


TeCLar 

HUIBSPART#ONE LITERALLY 
‘name (DEVSNAMESLEN) BYTE, 
file#driver WORD, 


functs BYTE, 
eer BYTE, 
devegran WORD 
devtsize owaRd, 
device BYTE, 
unit BYTE, 
devgunit WORD, 
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DUIBSPARTSTWO LITERALLY 
ORD, 


"initfio 

finishfio WORD, 
queuesio WORD, 
tancel fio 

devicesintatp POINTER, 
unitfintosp POINTER, 
update$timeout WORD, 
nua$buf fers WORD, 
priority BYTE, 
fixed$update § BYTE, 
max$butters BYTE, 
fill B 


YTE! 
DEVSUNITSINFOSELOCK LITERALLY ‘STRUCTURE( 


DUIBSPARTSONE 


DUIBSPARTSTWO) '; 


DECLARE 


$restore 


VF SSUTO LITERALLY 
VFSDENSITY LITERALLY ° 
VFSSIDES LITERALLY 
YF SMINI LITERALLY ° 


$save nolist 


it 


* xexcep. lit 
1/0 System Exception Code Mnesonics. 


£ 
t/ 


finclude(:flsxnerro.lit) 


{* 


OO he 
soe a pe : 


* 105 Synchronous Avoidable exception codes, 


#/ 


DECLARE 


f 


oe 


i 


ESNOUSER 
ESNOPREFIX 


108 Asynchronous 


DECLARE 


{t 


ESFEXIST 
ESFNEXIST 
ESDEVFD 
ESSUPPORT 
ESEMPTYSENTRY 
ESDIRFEND 
ESFACCESS 
ESFTYPE 
ESSHARE 
ESSPACE 
ESIDDR 

ESI 
ESFLUSHING 
ESTLLVOL 
ESDEVSOFFSLINE 
ESIFDR 


LITERALLY ‘OBOZ1H’, /* Job has no Default User Object #/ 
LITERALLY "O8022H's /# Job has no Detault Prefix Qbject +/ 


exceotion codes. 


LITERALLY ‘Q0020H', /# File Exists #/ 

LITERALLY ‘O0021H', /* Non- existant File #/ 

LITERALLY ‘G0022H', /# Device & File Driver Incompatable +/ 
LITERALLY ‘O0023H", /* Un-sup orted Request +/ 

LITERALLY ‘O0Q24H', /# Empty hinecto ory Entry #/ 


LITERALLY ‘00025H', [% End of Directory #/ 
LITERALLY ‘90024H', /# Access to File Not Granted #/ 


LITERALLY ‘G0927H', /* Bad File Type #/ 

LITERALLY ‘GO00Z8H', /* Improper File Sharing Requested #/ 
LITERALLY “Q0029H", /*# No Space Lert #/ 

LITERALLY ‘QO02AH', it aa Device Driver Request #/ 
LITERALLY “O002BH", /*# 1/0 Error #/ 

LITERALLY ‘G002CH', /* Connection is flushing requests #/ 
LITERALLY ‘O002DH', /* Tilegal Volume #/ 

LITERALLY “QOO2EH' /* Device Was Off Line #/ 


LITERALLY ‘“OQQ2FH'; /* Tllegal File Driver Request #/ 


# ESI0 expanded with unitstatus codes 


*/ 
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DECLARE 
ESIO$UNCLASS LITERALLY ‘OOOSOH', /* Unclassified #/ 
E$IO$S0FT LITERALLY ‘OOOSIH', /* Soft error #/ 
ESTOSHARD LITERALLY ‘00052H', /* Hard error ¥/ 
ESIOSOPRINT LITERALLY 'QOOS3H', /* Qperator intervention required #/ 
ESTOSWRPROT LITERALLY ‘00054H", /* Write protected #/ 
ESIOSNOSDATA LITERALLY ‘OOOSSH', /* No further data #/ 
ESIOSNODE LITERALLY ‘QO056H'; /* Mode viclation */ 
frestore 


$save nolist 


it 
* xioexc. lit 
t/ 
i* 
* [0 exception codes 
t/ 


DECLARE 
TOSUNCLASS LITERALLY “0°, 
TO$S0FT LITERALLY ‘1’, 
TGSHARD LITERALLY ‘2’, 
IOSQPRINT LITERALLY ‘3’, 
LOSHRPROT LITERALLY ‘4°, 
IQ$NOSDATA LITERALLY ‘', 
TOSMOQDE LITERALLY °6°3 
$restore 
$save nolist 
/* 
* xicfct. lit 
$ 
* IQ function codes 
+ 
+; 
DECLARE 
FSREAD LITERALLY ‘O', 
CEWRITE LITERALLY ‘1’, 
FESEEK LITERALLY ‘2°, 
FSSPECTAL LITERALLY ‘3', 
FSSTTACHSDEV LITERALLY ‘4°, 
FEDETACHSDEV LITERALLY ‘3’, 
FSOPEN LITERALLY ‘4’, 
FSCLOSE LITERALLY '7', 
FSGETCS LITERALLY 'G', 
FSGETFS LITERALLY °9', 
FSGETERT LITERALLY “10. , 
FESETEXT LITERALLY ty 
FENULLSCHSACCESS LITERALLY ‘12°, 
FSNULLSDELETE LITERALLY ‘13° 


FSRENANE LITERALLY ‘14° 
FSGETSPATHSCOMP LITERALLY ‘15° 
FSGETSDIRSENTRY LITERALLY ‘16° 
FSTRUNC LITERALLY ‘17° 
FSDETACH LITERALLY ‘18° 
FSNUMSFUNCT LITERALLY “19° 


a ae a ee) 
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/t 

* Function codes for internal use “eb 

* The rq$common$attach and common$io$task use FSATTACHSTHRU. 
ie req$update and cos@on$iostask use FSUPDATE. 


CLARE 
pune LITERALLY ‘19°, 


SUPDATE LITERALLY ‘20°; 

$rastore 
$save nolist 

{* 

* ea ores 

MX/86 I/0 System “type” literals. 

# 

*/ 


CLARE 
CONNECTION LITERALLY ‘TOKEN’, 


USER LITERALLY ‘TOKEN’ 
BLOCKSNUM = LITERALLY ‘ (3) BYTE’; 
$restore 
$save nolist 
it 
€ xiors. lit 
¢ 1/0 Request/Result Segment 
k 
*/ 
DECL 


AR 

TORSSPARTSONE LITERALLY 
“status WORD, 
unitsstatus WORD, 
actual WORD, 
actual$fill] 4QRD, 
device WORD, 
unit BYTE, 
funct BYTE, 
subfunct WORD, 
devSloc OWORD, 
buff fp POINTER 


IGRSSPARTSTWO LITERALLY 
WORD, 


“count 
count$fill WORD: 
aux$o POINTER 


link$for POINTER, 
link#back POINTER, 
respsabax MAILBOX, 
done BOOLEAN, 
iors$fill 

cancel $id TOKEN, 
conn$t TOKEN? , 


TOSREGS$RES$SEG LITERALLY ‘STRUCTURE ( 
TGRS$PARTSONE 
IORSSPARTSTWO! *; 
i+ 
pe number of actual bytes of data (i.8,., before links) 
¥ 


DECLARE 
TORSSDATASSIZE LITERALLY ‘30°; 
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Finclude(:flsxiofct. Lit) 


frestore 


$save nolist 


[t 
£ ynotif.ext 
f 


* External for notify support procedure 
# Called by random access supported drivers 
#/ 


aE PROCEDURE (unit, idata$p) EXTERNAL; 
DECLARE 


“00000H' 
“OO00LH 
00002H" 
00003H" 
“00004H" 
“Q0005H 
“D0006H" 
00007H" 


"NO008H' 


“OBO0GH' 
QaGOLH" 
‘OBOO2H' 
"QBO0SH" 
"GOG04H" 
“G800ad 


unit BYTE 
ddatasp POINTER; 
END notify; 
frestore 
$save nolist 
{tk 
* yxnerro,lit 
#/ 
DECLARE 
ESOK LITERALLY 
ESTIME LITERALLY 
ESMEM LITERALLY 
ESSUSY LITERALLY 
ESLIMIT LITERALLY 
ESCONTEXT LITERALLY 
ESEXIST LITERALLY 
ESSTATE LITERALLY 
ESNOTECONFIGURED LITERALLY 
DECLARE 
ESZERQSDIVIDE LITERALLY 
ESOVERFLOW LITERALLY 
ESTYPE LITERALLY 
ESBOUNDS LITERALLY 
ESPARAM LITERALLY 
ESRADSCALL LITERALLY 
frestore 
gsave nolist 
/+ 
¥ a tae 
t MX/86 Nucleus "type" literais. 
S 4 
¥} 
DECLARE 
TOKEN LITERALLY ‘SELECTOR’, 
SEGMENT LITERALLY ‘TOKEN’ 
TASK LITERALLY ‘TOKEN’, 
REGION LITERALLY ‘TOKEN’, 
SEMAPHORE LITERALLY ‘TOKEN’, 
MAILBOX LITERALLY ‘TOKEN’, 
108 LITERALLY ‘TOKEN’, 
EXTENSION LITERALLY ‘TOKEN 
DECLARE 
TSMAILBOX LITERALLY ‘O3H', 
TSSEGMENT LITERALLY ‘OSH’; 
frestore 
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fsave nolist 
i 
* xparam. lit 
# 1/0 Systea parameter literals. 
* 
#/ 
DECLARE 
DEVSNAMESLEN LITERALLY ‘14’, /* device name is 14 bytes #/ 
PATHSCOMPSLEN = LITERALLY ‘14", /® path component size #/ 
UP$COMP LITERALLY ''"* '', ff fa component character #/ 
ATHSSEP LITERALLY ‘''/''', /# path component seperator character #/ 
DEFSPREFIX$CHAR LITERALLY ‘''$'''3  /# default-prefix character #/ 
DECLARE 
ATTSDEVSTASKSSTACKS51ZE LITERALLY ‘512', 
CONNSJOBSDELETESTASKSSTACKSSIZE LITERALLY ‘512’, 
TIMERSTASKESSTACK$51ZE LITERALLY ‘S12’, 
COMMONSDRIVERSSTACKSSIZE LITERALLY ‘512°; 
DECLARE 
TOS$OS$EXTENSION LITERALLY °192'; /# OS extension vector #/ 
DECLARE 
XFACESQ$LEN LITERALLY ‘(S#2)', /* xface mbox queue length = 3#4 #/ 
ied CONNSDELSQ$L EN LITERALLY °(5#2)°3 /* conn jab-del abox queue length = 3#4 #/ 
rrestore 


fsave nolist 


it 
* xprerr.lit 
t/ 


[t 
* error codes 
+/ ; 
DECLARE 
ESOK LITERALLY ‘GO00H', 
ESIDDR LITERALLY ‘Q02AH': 
frestore 


$save nolist 


/*¥ 
* xtrsec lit 
ti 


DECLARE TRACKSSECTORSSTRUCT LITERALLY ‘STRUCTURE! 
sector WORD 
track WORD)’; 
frestore 
fsave nolist 
ik 
* ytsscw.ext 
t/ 


xts$set$outputdwaiting: PROCEDURE (ugatagp) EXTERNAL: 
DECLARE 
POINTER: 


udat ay 
END xtstsetSoutputfwai ting; 


frestore 
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$SAVE NOLIST 


} SY 
# xtstia,ext 
#/ 


: ternal Declaration 
é 


tiger support procedure. 


it 

€ Ey 
# £0 
* 


/ 


set$baud$ratescount: PROCEDURE (command port, counter pat timer type, 
counter _number, rate count) EXTERNAL; 


DECLARE 
(command port, counter port, rate count) WORD, 
{timer type, counter _number) BYTE; 
END set$baud$ratefcount; 


$RESTORE 


$save nolist 
[t 


* xradsf. lit 
f Randoa-Access driver Special-Function Mnemonics. 


+ 
*/ 
CLARE 
FSSFORMATSTRACK LITERALLY ‘9's /* format a track #/ 


# Format info structure to for@at cone track on 
* a disk(hard or floppy) 
* used by 204 & 206 drivers 


‘ 
#/ 
DECLARE 
FORMATSINFOSSTRUCT LITERALLY ‘STRUCTURE ‘ 
trackSnue WOR} 
track$interleave WOR), 
trackskew tl) 
fill $char BYTES "s 
{t 


* Device label epeela: function. Asks driver to supply 
* device information for named file label. 
$ 


*/ 


ECLARE 
FSSDEVICESLABEL LITERALLY °3°; 


/t 
# Special tape functions. 
* 
*/ 
DECLARE 
FSSREWIND LITERALLY ‘7°, 
FO$READSFILESMARK LITERALLY ‘8°, 
FOSWRITESFILESMARK LITERALLY °9°, 
FOSRETENSION LITERALLY ‘£973 
$restore 
¥¥% 


B-50 





Primary references are underscored. 


assembly language iii, 8-1 
attach device requests 4-1 


baud rate 7-16, 7-19 
BEGLINSLONGSTERMSOP procedure 5-8 
buffered devices 7-17, /-25 
buffers 2-6, 2-7 


CANCELSIO procedure 2-5, 3-3, 6-4, A-6 
cancel requests 4-2 
close requests 4-2 
common device driver 1-3, 5-1 
device information table 3-8 
example B-2 
support routines A-1, B-55 
common device 3-1 
comminication levels 1-1 
configuration 2-1, 8-1 
connection 2-16 
creating DUIBs 2-8 
custom device drivers 1-3, 6-1 
custom devices 3-2 
cylinder 3-11 


data storage area 3-9, 3-13 
data structures 3-7, 3-12 
DEFAULTSFINISH procedure 5-3 
DEFAULTSINIT procedure 5-2 
DEFAULTSSTOP procedure 5-5 
detach device requests 4-2 
device 

buffered 7-17, 7-25 

granularity 2-4 

interfaces 2-13 

number 1-2, 2-5, 2-11 
device data storage area 3-9, 3-13, A-3, A-9 
device driver 

interfaces 2-1 

sample INCLUDE files 8-55 

type 1-3 
DEVICESFINISH procedure 3-10, 5-2 
Device Information Table 2-5, 3-8, 7-3, 7-27 
DEVICESINIT procedure 3-10, 5-2 ~ 
DEVICESINTERRUPT procedure 3-10, 5-5 
DEVICESSTART procedure 3-10, 5-3 


Ww 
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INDEX (continued) 


DEVICESSTOP procedure 3-10, 5-4 
device-unit information block (DUIB) 2-2 
creation 2-8 
structure 2-2 
use of 2-7, 4-3 
device-unit 
name 2-3 
number 1-2, 2-5 
doubly linked list 6-5 
driver configuration 8-1 
DQSATTACH system call 2-3, 3-4 
DQSCREATE system call 2-3, 3-4 
DUIB, see: device-unit information block 


ENDSLONGSTERMSOP procedure 5-9 
examples of device drivers B-l 
device driver INCLUDE files B-55 
disk controller driver B-8 
printer driver B-2 
terminal driver B-29 


file connection 2-16 

file drivers 1-2, 2-3 

FINISHSLO procedure 2-5, 3-2, 3-10, 6-2, Aq3: 
fixed updating 2-6 

FORMAT command 5-11 


functions 2-3, 2-11 


GETSIORS procedure 5-10 
granularity 2-4, 2-7 


L206DS.P86 disk-controller driver source file B-8 
INITSIO procedure 2-5, 3-2, A-1, A-9 
Intel-supplied routines 5-1 
Interactive Configuration Utility (ICU) 8-1 
interfaces to the device driver 2-1 
interrupt 
handlers and tasks 3-3 
level 3-8, 7-5 
task A-3 
task priority 3-9 
type 7-13, 7-22 
INTERRUPTSTASK procedure 3-3, AD 
I/O functions 2-3 
I/O request/result segment (IORS) 1-3, 2-9, A-5, A-7, A-11] 
structure 2-9 
use of 4-3 
I/O requests 1-3, 4-1 
I/O System interfaces 2-1 
I/O System responses 4-1 
I/O System-supplied routines 5-1 
IPRNTR.P86 printer driver source file k-2 





levels of communication 1-1 
linked list 6-5 
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long-term operations 5-8 
modem 7-8 


name of device-unit 2-2 
notify procedure 2-14, 5-6 
numbering of devices 1-2 


open requests 4-2 


parity 7-7 

PL/M-86 iii, 5-1l, 8-1 
portable device drivers 3-14 
priority 3-9 


QUEUESIO procedure 2-5, 3-3, 6-3, A-5 


RADS procedure-name prefix (iRMX 88 systems only) 3-2, A-1l 
random access device drivers 1-3, 5-l 

random access devices 3-1 

random access driver example B-8 

read requests 4-2 

request queue 6-5 

requests 1-3, 4-l 

requirements for using the common device driver 3-1 

retry limit 3-11 

RQSASPHYSICALSATTACHSDEVICE system cal] 2-3, 3-4, 3-5, 6-4, A-l 
RQSELVL system call A-9 

ROSFORMAT system call 5-11 

RQSSETSINTERRUPT system call A-9 


SEEKSCOMPLETE procedure 3-11, 5-7 

seek requests 4-2 ies 

set output waiting (XTSSSETSOUTPUTSWAITING) procedure 7-18, 7-24 
signal character 2-15 

source files, device drivers B-1l 

special requests 4-2 

stack size 3-9 

support (INCUDE) files B-55 


tape drives 2-14, 5-8 
rewinding of 5-8 
terminal 
attributes 2-15 
baud rate 7-16, 7-19 
Device Information Table 2-5, 3-8, 7-3, 7-27 
devices 3-3 
driver example B-29 
drivers 7-1 
flags 7-8, 7-14 


modem /-8 

parity 7-7 
terminal answer (TERMSANSWER) procedure 7-17, 7-20, 7-27 
terminal check (TERMSCHECK) procedure 7-17, 7-22, 7-27 
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terminal controller data 7-14, 7-27 

termina] finish (TERMSFINISH) procedure 7-17, 7-19, 7-27 
terminal hangup (TERMSHANGUP) procedure 7-17, 7-21, 7-27 
terminal initialization (TERMSINIT) procedure 7-17, 7-18, 7-27 
terminal output (TERMSOUT) procedure 7-17, 7-24, 7-27 

terminal setup (TERMSSETUP) procedure 7-17, 7-19, 7-27 
Terminal Support Code 7-11 

terminal unit data 7-4, 7-14, 7-27 

track size 3-11 

types of device drivers 1-3 





Unit Information Table 2-5, 3-10, 7-6 
unit number 1-2, 2-5, 2-11 

unit status codes 2-10 

updating output to a device 2-6 

using DUIBs 2-7 

volume granularity 2-7 


write requests 4-2 


X8274.P86 terminal driver source file B--29 
XTSSSETSOUTPUTSWAITING procedure 7-24 
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